octopize.deploy_tool 2.6.0__tar.gz → 2.7.0__tar.gz

{octopize_deploy_tool-2.6.0 → octopize_deploy_tool-2.7.0}/.gitignore

@@ -67,9 +67,9 @@ Thumbs.db
 .avatar-templates
 .deployment_state.yaml
 .env
-!tests/fixtures/**/expected/.env
+!tests/fixtures/**/.env
 config.*.yaml
 !config.example.yaml
-
+.deployment_states/*
 # TLS test fixtures created dynamically by the test suite
 tls/

{octopize_deploy_tool-2.6.0 → octopize_deploy_tool-2.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: octopize.deploy_tool
-Version: 2.6.0
+Version: 2.7.0
 Summary: Deployment configuration tool for Octopize Avatar platform
 Project-URL: Homepage, https://octopize.io
 Project-URL: Documentation, https://docs.octopize.io/docs/deploying/self-hosted
@@ -21,11 +21,9 @@ Requires-Python: >=3.13
 Requires-Dist: httpx>=0.28.0
 Requires-Dist: jinja2>=3.1.0
 Requires-Dist: pandas>=3.0.0
+Requires-Dist: python-on-whales>=0.76.0
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: rich>=13.0.0
-Provides-Extra: dev
-Requires-Dist: pyright>=1.1.402; extra == 'dev'
-Requires-Dist: pytest>=7.0; extra == 'dev'
 Description-Content-Type: text/markdown
 
 # Octopize Avatar Deployment Tool

{octopize_deploy_tool-2.6.0 → octopize_deploy_tool-2.7.0}/pyproject.toml

@@ -4,14 +4,12 @@ build-backend = "hatchling.build"
 
 [project]
 name = "octopize.deploy_tool"
-version = "2.6.0"
+version = "2.7.0"
 description = "Deployment configuration tool for Octopize Avatar platform"
 readme = "README.md"
 requires-python = ">=3.13"
 license = { text = "MIT" }
-authors = [
-    { name = "Octopize", email = "contact@octopize.io" }
-]
+authors = [{ name = "Octopize", email = "contact@octopize.io" }]
 keywords = ["octopize", "avatar", "deployment", "configuration"]
 classifiers = [
     "Development Status :: 4 - Beta",
@@ -30,12 +28,18 @@ dependencies = [
     "rich>=13.0.0",
     "httpx>=0.28.0",
     "pandas>=3.0.0",
+    "python-on-whales>=0.76.0",
 ]
 
-[project.optional-dependencies]
+[dependency-groups]
 dev = [
-    "pytest>=7.0",
+    "pytest>=9",
+    "mypy>=1.20.0",
     "pyright>=1.1.402",
+    "types-pyyaml>=6.0.12.20241230",
+    "pandas-stubs>=3.0.0",
+    "pytest-httpx>=0.36.0",
+    "pytest-cov>=7.1.0",
 ]
 
 [project.scripts]
@@ -54,36 +58,30 @@ packages = ["src/octopize_avatar_deploy"]
 "src" = ""
 
 [tool.hatch.build.targets.sdist]
-include = [
-    "src/",
-    "tests/",
-    "README.md",
-    "pyproject.toml",
-]
+include = ["src/", "tests/", "README.md", "pyproject.toml"]
 
 [tool.pytest.ini_options]
 # Test discovery
-testpaths = ["tests"]
-python_files = ["test_*.py"]
-python_classes = ["Test*"]
-python_functions = ["test_*"]
+testpaths = "tests"
+filterwarnings = ["error"]
+# Recommended by pytest
+pythonpath = "src"
 
 # Output options
 addopts = [
-    "-v",                          # Verbose output
-    "--strict-markers",            # Error on unknown markers
-    "--tb=short",                  # Short traceback format
-    "--color=yes",                 # Colored output
-    "-ra",                         # Show summary of all test results
+    # Recommended by pytest
+    # https://docs.pytest.org/en/stable/explanation/goodpractices.html#tests-outside-application-code
+
+    "--import-mode=importlib",
+    "--strict-markers",        # Error on unknown markers
+    "--tb=short",              # Short traceback format
+    "--color=yes",             # Colored output
+    "-ra",                     # Show summary of all test results
 ]
 
 [tool.coverage.run]
 source = ["src/octopize_avatar_deploy"]
-omit = [
-    "*/tests/*",
-    "*/__pycache__/*",
-    "*/.venv/*",
-]
+omit = ["*/tests/*", "*/__pycache__/*", "*/.venv/*"]
 
 [tool.coverage.report]
 exclude_lines = [
@@ -99,15 +97,6 @@ exclude_lines = [
 [tool.ruff]
 extend = "../../../ruff.toml"
 
-[dependency-groups]
-dev = [
-    "mypy>=1.20.0",
-    "pyright>=1.1.402",
-    "types-pyyaml>=6.0.12.20241230",
-    "pandas-stubs>=3.0.0",
-    "pytest-httpx>=0.36.0",
-]
-
 [tool.pyright]
 include = ["src/octopize_avatar_deploy"]
 pythonVersion = "3.13"

{octopize_deploy_tool-2.6.0 → octopize_deploy_tool-2.7.0}/src/octopize_avatar_deploy/__init__.py

@@ -1,6 +1,5 @@
 """Octopize Avatar Deployment Tool."""
 
-from .cli import main
 from .configure import DeploymentConfigurator, DeploymentRunner
 from .printer import ConsolePrinter, Printer, SilentPrinter
 from .version_compat import (
@@ -11,9 +10,8 @@ from .version_compat import (
     validate_template_version,
 )
 
-__version__ = "2.6.0"
+__version__ = "2.7.0"
 __all__ = [
-    "main",
     "DeploymentRunner",
     "DeploymentConfigurator",
     "Printer",

octopize_deploy_tool-2.7.0/src/octopize_avatar_deploy/application/__init__.py

@@ -0,0 +1 @@
+"""Application sub-package for deployment tool refactor (Phase 1)."""

octopize_deploy_tool-2.7.0/src/octopize_avatar_deploy/application/apply_command.py

@@ -0,0 +1,137 @@
+"""ApplyCommand: the Phase 1 application entry point for the apply sub-command.
+
+``apply`` copies a fully rendered ``generated/`` directory from a versioned
+state slot into ``generated_files/`` (the directory consumed by Docker Compose)
+and updates the ``currently_deployed`` symlink so the active version is always
+traceable.
+
+The operation is idempotent: applying the same version twice produces the same
+``generated_files/`` content and symlink target.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from octopize_avatar_deploy.application.deployment_paths import DeploymentPaths
+from octopize_avatar_deploy.application.ports import DirectoryCopier, SymlinkUpdater
+from octopize_avatar_deploy.domain.version_id import VersionId
+
+
+class ApplyError(Exception):
+    """Raised when apply fails due to an operator-fixable problem.
+
+    Covers missing ``--version`` argument, references to versions whose
+    ``generated/`` directory does not yet exist (i.e. ``render`` was never run
+    for that version), or any filesystem error that maps to an operator action.
+
+    Distinct from plain ``ValueError`` or ``FileNotFoundError``, which indicate
+    programming-contract violations (bugs in the tool) and should surface with a
+    full traceback.
+    """
+
+
+@dataclass
+class ApplyCommandArgs:
+    """Arguments for the apply command.
+
+    ``version`` must be provided (e.g. ``"v1"``).
+    """
+
+    app_root: Path
+    version: str  # explicit version label, e.g. "v1"
+
+
+@dataclass
+class ApplyCommandResult:
+    """Result returned by :meth:`ApplyCommand.run`."""
+
+    version: VersionId
+    output_dir: Path
+    symlink_target: Path
+
+
+class ApplyCommand:
+    """Orchestrate the apply use case.
+
+    Copies ``.deployment_states/vX/generated/`` into ``generated_files/`` and
+    updates the ``currently_deployed`` symlink.
+
+    All side effects (directory copy and symlink update) are injected as ports
+    so the full use case can be exercised in tests with in-memory doubles.
+
+    Args:
+        directory_copier: Port that performs the full recursive copy from the
+            versioned ``generated/`` directory to ``generated_files/``.
+        symlink_updater: Port that creates or replaces the
+            ``currently_deployed`` symlink.
+    """
+
+    def __init__(
+        self,
+        *,
+        directory_copier: DirectoryCopier,
+        symlink_updater: SymlinkUpdater,
+    ) -> None:
+        self._directory_copier = directory_copier
+        self._symlink_updater = symlink_updater
+
+    def run(self, args: ApplyCommandArgs) -> ApplyCommandResult:
+        """Execute the apply use case end-to-end.
+
+        Flow:
+
+        1. Validate argument combinations.
+        2. Parse the target version label.
+        3. Confirm that ``render`` has been run for this version (the
+           ``generated/`` directory exists).
+        4. Copy ``.deployment_states/vX/generated/`` → ``generated_files/``
+           (full recursive copy — not a symlink — so operator edits in
+           ``generated_files/`` never affect the versioned reference).
+        5. Update ``.deployment_states/currently_deployed`` symlink → ``vX``.
+        6. Return a result.
+
+        Args:
+            args: Apply command arguments.
+
+        Returns:
+            :class:`ApplyCommandResult` with the resolved version, the
+            ``generated_files/`` output directory, and the symlink target path.
+
+        Raises:
+            ApplyError: For any operator-fixable problem: a version whose
+                ``generated/`` directory does not exist, or a missing version
+                argument.
+        """
+        try:
+            return self._run(args)
+        except ApplyError:
+            raise
+        except (ValueError, FileNotFoundError) as exc:
+            raise ApplyError(str(exc)) from exc
+
+    def _run(self, args: ApplyCommandArgs) -> ApplyCommandResult:
+        """Internal implementation called by :meth:`run`."""
+        # 1. Parse version.
+        version = VersionId.parse(args.version)
+        paths = DeploymentPaths(app_root=args.app_root, version=version)
+
+        # 2. Verify that render has been run (generated/ must exist).
+        if not self._directory_copier.source_exists(paths.generated_dir):
+            raise ApplyError(
+                f"Version {version.label!r} has not been rendered yet. "
+                f"Run 'render --version {version.label}' first."
+            )
+
+        # 3. Copy generated/ → generated_files/.
+        self._directory_copier.copy(paths.generated_dir, paths.generated_files_dir)
+
+        # 4. Update currently_deployed symlink.
+        self._symlink_updater.update(paths.currently_deployed_symlink, paths.version_dir)
+
+        return ApplyCommandResult(
+            version=version,
+            output_dir=paths.generated_files_dir,
+            symlink_target=paths.version_dir,
+        )

octopize_deploy_tool-2.7.0/src/octopize_avatar_deploy/application/checks.py

@@ -0,0 +1,362 @@
+"""Pre-flight and general-purpose check infrastructure.
+
+Provides a composable check system used by top-level commands (``install``,
+``update``, etc.) to run ordered guard checks before executing their main
+pipeline.  Each check is an independent unit with its own dependencies and
+returns a typed result.  A :class:`PreflightCheck` orchestrates a list of
+checks, short-circuits on the first abort, and collects results into a
+:class:`PreflightResult`.
+
+Architecture:
+- :class:`CheckResult` — common Protocol; every concrete result must implement it.
+- :class:`Check` — Protocol for runnable checks; each check receives its deps
+  at construction and exposes a ``run(app_root)`` method.
+- :class:`VolumeCheck` / :class:`DeploymentStateCheck` — concrete checks.
+- :class:`PreflightResult` — aggregated results with typed accessors.
+- :class:`PreflightCheck` — orchestrator that composes a list of checks.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Literal, Protocol
+
+from octopize_avatar_deploy.application.ports import (
+    DeploymentStateRepository,
+    DockerClient,
+)
+from octopize_avatar_deploy.input_gatherer import InputGatherer
+from octopize_avatar_deploy.printer import Printer
+
+# ---------------------------------------------------------------------------
+# Known Avatar Docker volumes
+# ---------------------------------------------------------------------------
+
+#: The canonical set of Docker volume names created by the Avatar stack.
+#: Passed to :class:`VolumeCheck` by default in production wiring.
+AVATAR_KNOWN_VOLUMES: list[str] = [
+    "avatar_postgres_data",
+    "avatar_seaweedfs_data",
+    "avatar_seaweedfs_metadata",
+    "avatar_seaweedfs_blocks",
+]
+
+
+# ---------------------------------------------------------------------------
+# Protocols
+# ---------------------------------------------------------------------------
+
+
+class CheckResult(Protocol):
+    """Common interface for all check results.
+
+    Every concrete check result must expose an ``aborted`` attribute so that
+    :class:`PreflightResult` can aggregate outcomes without knowing the
+    specific result type.
+    """
+
+    @property
+    def aborted(self) -> bool:
+        """Whether this check caused the overall operation to be aborted."""
+        ...
+
+
+class Check(Protocol):
+    """Protocol for a single runnable pre-flight check.
+
+    Implementations receive all required dependencies at construction time.
+    The ``run`` method is kept narrow: it receives only the ``app_root`` path
+    that is common to every check.
+    """
+
+    def run(self, app_root: Path) -> CheckResult:
+        """Execute the check and return a typed result.
+
+        Args:
+            app_root: Operator's working directory (the deployment root).
+
+        Returns:
+            A :class:`CheckResult` implementation. If ``result.aborted`` is
+            ``True`` the caller should not proceed further.
+        """
+        ...
+
+
+# ---------------------------------------------------------------------------
+# VolumeCheck
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class VolumeCheckResult:
+    """Result of the Docker volume pre-flight check.
+
+    Attributes:
+        existing_volumes: Volume names that were found on the host.
+        aborted: ``True`` if the operator chose not to continue.
+    """
+
+    existing_volumes: list[str]
+    aborted: bool
+
+
+class VolumeCheck:
+    """Check whether known Avatar Docker volumes already exist on the host.
+
+    If any of ``known_volumes`` are found:
+    - In interactive mode: the operator is warned and asked for explicit confirmation.
+    - In non-interactive mode: the check fails by default (aborts).
+
+    Args:
+        docker_client: Port for listing Docker volumes.
+        input_gatherer: Port for interactive confirmation prompts.
+        printer: Port for warning output.
+        known_volumes: Volume names to look for. Defaults to
+            :data:`AVATAR_KNOWN_VOLUMES` in production.
+        interactive: Whether to prompt the operator or fail by default.
+    """
+
+    def __init__(
+        self,
+        docker_client: DockerClient,
+        input_gatherer: InputGatherer,
+        printer: Printer,
+        known_volumes: list[str],
+        interactive: bool = True,
+    ) -> None:
+        self._docker_client = docker_client
+        self._input_gatherer = input_gatherer
+        self._printer = printer
+        self._known_volumes = known_volumes
+        self._interactive = interactive
+
+    def run(self, app_root: Path) -> VolumeCheckResult:  # noqa: ARG002
+        """Detect existing volumes and prompt for confirmation if any are found.
+
+        Args:
+            app_root: Unused by this check; present to satisfy the :class:`Check`
+                protocol so all checks share the same ``run`` signature.
+
+        Returns:
+            :class:`VolumeCheckResult` with the found volumes and abort flag.
+        """
+        all_volumes = self._docker_client.list_volume_names()
+        existing = [v for v in self._known_volumes if v in all_volumes]
+
+        if not existing:
+            return VolumeCheckResult(existing_volumes=[], aborted=False)
+
+        for name in existing:
+            self._printer.print_warning(
+                f"Volume '{name}' already exists. "
+                "New credentials generated by this install will not match "
+                "the existing data in that volume."
+            )
+
+        if not self._interactive:
+            # In non-interactive mode, fail by default if volumes are present
+            return VolumeCheckResult(existing_volumes=existing, aborted=True)
+
+        confirmed = self._input_gatherer.prompt_yes_no(
+            "Existing volumes were found. Do you still want to proceed with a fresh install?",
+            default=False,
+            key="preflight.volume_check.confirm",
+        )
+
+        return VolumeCheckResult(existing_volumes=existing, aborted=not confirmed)
+
+
+# ---------------------------------------------------------------------------
+# DeploymentStateCheck
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class DeploymentStateCheckResult:
+    """Result of the existing deployment state pre-flight check.
+
+    Attributes:
+        state: What was found in ``.deployment_states/``:
+            - ``"none"`` — directory does not exist; fresh install.
+            - ``"in_progress"`` — most recent version is incomplete.
+            - ``"completed"`` — at least one completed version exists.
+        aborted: ``True`` if the operator chose not to continue.
+        resume: ``True`` if the operator chose to resume an in-progress version.
+    """
+
+    state: Literal["none", "in_progress", "completed"]
+    aborted: bool
+    resume: bool = False
+
+
+class DeploymentStateCheck:
+    """Check whether a previous deployment state exists in ``.deployment_states/``.
+
+    Handles three cases:
+
+    - **No state** — nothing to do, continue silently.
+    - **In-progress** — in interactive mode, offer to resume; in non-interactive mode,
+      fail by default.
+    - **Completed** — in interactive mode, warn and ask for confirmation;
+      in non-interactive mode, fail by default (destructive fresh install requires
+      explicit operator confirmation).
+
+    Args:
+        repository: Port for inspecting existing versioned state.
+        input_gatherer: Port for interactive prompts.
+        printer: Port for warning output.
+        interactive: Whether to prompt the operator or fail by default.
+    """
+
+    def __init__(
+        self,
+        repository: DeploymentStateRepository,
+        input_gatherer: InputGatherer,
+        printer: Printer,
+        interactive: bool = True,
+    ) -> None:
+        self._repository = repository
+        self._input_gatherer = input_gatherer
+        self._printer = printer
+        self._interactive = interactive
+
+    def run(self, app_root: Path) -> DeploymentStateCheckResult:
+        """Inspect ``.deployment_states/`` and prompt accordingly.
+
+        Args:
+            app_root: Operator's working directory (the deployment root).
+
+        Returns:
+            :class:`DeploymentStateCheckResult` describing what was found and
+            what the operator decided.
+        """
+        versions = self._repository.list_versions(app_root)
+
+        if not versions:
+            return DeploymentStateCheckResult(state="none", aborted=False, resume=False)
+
+        # Check if the most recent version is in-progress.
+        latest = versions[-1]
+        latest_doc = self._repository.get(app_root, latest)
+
+        if not latest_doc.is_complete():
+            return self._handle_in_progress(latest.label)
+
+        return self._handle_completed()
+
+    def _handle_in_progress(self, version_label: str) -> DeploymentStateCheckResult:
+        self._printer.print_warning(
+            f"An in-progress configuration was found (version {version_label}). "
+            "You can resume it or start a completely fresh install."
+        )
+
+        if not self._interactive:
+            # In non-interactive mode, fail by default
+            return DeploymentStateCheckResult(state="in_progress", aborted=True, resume=False)
+
+        resume = self._input_gatherer.prompt_yes_no(
+            f"Resume the in-progress configuration ({version_label})?",
+            default=True,
+            key="preflight.deployment_state_check.resume",
+        )
+        if resume:
+            return DeploymentStateCheckResult(state="in_progress", aborted=False, resume=True)
+        # Operator declined to resume — abort so they can decide what to do.
+        return DeploymentStateCheckResult(state="in_progress", aborted=True, resume=False)
+
+    def _handle_completed(self) -> DeploymentStateCheckResult:
+        self._printer.print_warning(
+            "A completed deployment configuration already exists. "
+            "Running install will create a completely fresh deployment with "
+            "new passwords and secrets — the previous configuration will not be carried forward. "
+            "Use 'update' instead to carry values forward from the current deployment."
+        )
+
+        if not self._interactive:
+            # In non-interactive mode, fail by default for a destructive fresh install
+            return DeploymentStateCheckResult(state="completed", aborted=True, resume=False)
+
+        confirmed = self._input_gatherer.prompt_yes_no(
+            "Do you want to proceed with a fresh install anyway?",
+            default=False,
+            key="preflight.deployment_state_check.confirm_fresh",
+        )
+        return DeploymentStateCheckResult(state="completed", aborted=not confirmed, resume=False)
+
+
+# ---------------------------------------------------------------------------
+# PreflightResult
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class PreflightResult:
+    """Aggregated result of all pre-flight checks.
+
+    ``results`` is ordered — each entry corresponds to a check in the same
+    position as the list passed to :class:`PreflightCheck`.  If the checker
+    short-circuited, later entries will be absent.
+
+    Args:
+        results: Ordered list of individual :class:`CheckResult` objects.
+    """
+
+    results: list[CheckResult] = field(default_factory=list)
+
+    def aborted(self) -> bool:
+        """Return ``True`` if any check requested an abort."""
+        return any(r.aborted for r in self.results)
+
+    def resume(self) -> bool:
+        """Return ``True`` if the operator chose to resume an in-progress state.
+
+        Scans ``results`` for a :class:`DeploymentStateCheckResult` and returns
+        its ``resume`` flag.  Returns ``False`` if no such result is present.
+        """
+        for result in self.results:
+            if isinstance(result, DeploymentStateCheckResult):
+                return result.resume
+        return False
+
+
+# ---------------------------------------------------------------------------
+# PreflightCheck
+# ---------------------------------------------------------------------------
+
+
+class PreflightCheck:
+    """Run an ordered list of checks, short-circuiting on first abort.
+
+    Collects each check's result into a :class:`PreflightResult`.  If a check
+    returns ``aborted=True`` the remaining checks are skipped immediately.
+
+    This class is injected into :class:`~application.install_command.InstallCommand`
+    and can be given any list of :class:`Check` implementations, making it
+    reusable for future commands (``update``, etc.) that need their own guard
+    checks.
+
+    Args:
+        checks: Ordered list of check instances to run.
+    """
+
+    def __init__(self, checks: list[Check]) -> None:
+        self._checks = checks
+
+    def run(self, app_root: Path) -> PreflightResult:
+        """Execute all checks in order, returning an aggregated result.
+
+        Args:
+            app_root: Operator's working directory forwarded to each check.
+
+        Returns:
+            :class:`PreflightResult` containing all executed check results.
+            If the first check aborts, subsequent check results are not included.
+        """
+        collected: list[CheckResult] = []
+        for check in self._checks:
+            result = check.run(app_root)
+            collected.append(result)
+            if result.aborted:
+                break  # short-circuit
+        return PreflightResult(results=collected)