redeploy 0.2.57__tar.gz → 0.2.58__tar.gz

{redeploy-0.2.57 → redeploy-0.2.58}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: redeploy
-Version: 0.2.57
+Version: 0.2.58
 Summary: Infrastructure migration toolkit: detect → plan → apply
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
@@ -32,17 +32,17 @@ Requires-Dist: mcp>=1.0; extra == "mcp"
 
 ## AI Cost Tracking
 
-![PyPI](https://img.shields.io/badge/pypi-costs-blue) ![Version](https://img.shields.io/badge/version-0.2.57-blue) ![Python](https://img.shields.io/badge/python-3.9+-blue) ![License](https://img.shields.io/badge/license-Apache--2.0-green)
+![PyPI](https://img.shields.io/badge/pypi-costs-blue) ![Version](https://img.shields.io/badge/version-0.2.58-blue) ![Python](https://img.shields.io/badge/python-3.9+-blue) ![License](https://img.shields.io/badge/license-Apache--2.0-green)
 ![AI Cost](https://img.shields.io/badge/AI%20Cost-$7.50-orange) ![Human Time](https://img.shields.io/badge/Human%20Time-28.9h-blue) ![Model](https://img.shields.io/badge/Model-openrouter%2Fqwen%2Fqwen3--coder--next-lightgrey)
 
-- 🤖 **LLM usage:** $7.5000 (77 commits)
-- 👤 **Human dev:** ~$2886 (28.9h @ $100/h, 30min dedup)
+- 🤖 **LLM usage:** $7.5000 (78 commits)
+- 👤 **Human dev:** ~$2890 (28.9h @ $100/h, 30min dedup)
 
 Generated on 2026-04-21 using [openrouter/qwen/qwen3-coder-next](https://openrouter.ai/qwen/qwen3-coder-next)
 
 ---
 
-![PyPI](https://img.shields.io/badge/pypi-redeploy-blue) ![Version](https://img.shields.io/badge/version-0.2.57-blue) ![Python](https://img.shields.io/badge/python-3.10+-blue) ![License](https://img.shields.io/badge/license-Apache--2.0-green)
+![PyPI](https://img.shields.io/badge/pypi-redeploy-blue) ![Version](https://img.shields.io/badge/version-0.2.58-blue) ![Python](https://img.shields.io/badge/python-3.10+-blue) ![License](https://img.shields.io/badge/license-Apache--2.0-green)
 
 Infrastructure migration and device deploy toolkit — VPS, Raspberry Pi kiosk, Podman Quadlet, k3s.
 

{redeploy-0.2.57 → redeploy-0.2.58}/README.md

@@ -3,17 +3,17 @@
 
 ## AI Cost Tracking
 
-![PyPI](https://img.shields.io/badge/pypi-costs-blue) ![Version](https://img.shields.io/badge/version-0.2.57-blue) ![Python](https://img.shields.io/badge/python-3.9+-blue) ![License](https://img.shields.io/badge/license-Apache--2.0-green)
+![PyPI](https://img.shields.io/badge/pypi-costs-blue) ![Version](https://img.shields.io/badge/version-0.2.58-blue) ![Python](https://img.shields.io/badge/python-3.9+-blue) ![License](https://img.shields.io/badge/license-Apache--2.0-green)
 ![AI Cost](https://img.shields.io/badge/AI%20Cost-$7.50-orange) ![Human Time](https://img.shields.io/badge/Human%20Time-28.9h-blue) ![Model](https://img.shields.io/badge/Model-openrouter%2Fqwen%2Fqwen3--coder--next-lightgrey)
 
-- 🤖 **LLM usage:** $7.5000 (77 commits)
-- 👤 **Human dev:** ~$2886 (28.9h @ $100/h, 30min dedup)
+- 🤖 **LLM usage:** $7.5000 (78 commits)
+- 👤 **Human dev:** ~$2890 (28.9h @ $100/h, 30min dedup)
 
 Generated on 2026-04-21 using [openrouter/qwen/qwen3-coder-next](https://openrouter.ai/qwen/qwen3-coder-next)
 
 ---
 
-![PyPI](https://img.shields.io/badge/pypi-redeploy-blue) ![Version](https://img.shields.io/badge/version-0.2.57-blue) ![Python](https://img.shields.io/badge/python-3.10+-blue) ![License](https://img.shields.io/badge/license-Apache--2.0-green)
+![PyPI](https://img.shields.io/badge/pypi-redeploy-blue) ![Version](https://img.shields.io/badge/version-0.2.58-blue) ![Python](https://img.shields.io/badge/python-3.10+-blue) ![License](https://img.shields.io/badge/license-Apache--2.0-green)
 
 Infrastructure migration and device deploy toolkit — VPS, Raspberry Pi kiosk, Podman Quadlet, k3s.
 

{redeploy-0.2.57 → redeploy-0.2.58}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "redeploy"
-version = "0.2.57"
+version = "0.2.58"
 description = "Infrastructure migration toolkit: detect → plan → apply"
 readme = "README.md"
 requires-python = ">=3.11"

{redeploy-0.2.57 → redeploy-0.2.58}/redeploy/__init__.py

@@ -7,7 +7,7 @@ Public API (stable from 0.2.0, semver guaranteed)::
 
 Everything not listed in ``__all__`` is internal and may change without notice.
 """
-__version__ = "0.2.57"
+__version__ = "0.2.58"
 
 # ── Core models ───────────────────────────────────────────────────────────────
 from .models import (  # noqa: F401

{redeploy-0.2.57 → redeploy-0.2.58}/redeploy/iac/docker_compose.py

@@ -399,6 +399,40 @@ class DockerComposeParser:
     def _parse_service_command(self, cfg: dict) -> Optional[str]:
         return str(cfg["command"]) if cfg.get("command") else None
 
+    def _build_service_info(
+        self,
+        *,
+        name: str,
+        cfg: dict,
+        image: Optional[str],
+        ports: list[PortInfo],
+        volumes: list[VolumeInfo],
+        env: dict[str, str],
+        env_files: list[str],
+        svc_networks: list[str],
+        depends_on: list[str],
+        healthcheck: Optional[str],
+        build_context: Optional[str],
+        replicas: int,
+        labels: dict[str, str],
+    ) -> ServiceInfo:
+        return ServiceInfo(
+            name=name,
+            image=image,
+            ports=ports,
+            volumes=volumes,
+            env=env,
+            env_files=env_files,
+            networks=svc_networks,
+            depends_on=depends_on,
+            healthcheck=healthcheck,
+            restart=cfg.get("restart"),
+            command=self._parse_service_command(cfg),
+            build_context=build_context,
+            replicas=replicas,
+            labels=labels,
+        )
+
     def _parse_service(self, name: str, cfg: dict,
                        env_context: dict[str, str],
                        spec: ParsedSpec) -> ServiceInfo:
@@ -413,18 +447,17 @@ class DockerComposeParser:
         replicas = self._parse_service_replicas(cfg)
         labels = self._parse_service_labels(cfg)
 
-        return ServiceInfo(
+        return self._build_service_info(
             name=name,
+            cfg=cfg,
             image=image,
             ports=ports,
             volumes=volumes,
             env=env,
             env_files=env_files,
-            networks=svc_networks,
+            svc_networks=svc_networks,
             depends_on=depends_on,
             healthcheck=healthcheck,
-            restart=cfg.get("restart"),
-            command=self._parse_service_command(cfg),
             build_context=build_context,
             replicas=replicas,
             labels=labels,

redeploy-0.2.58/redeploy/models/blueprint.py

@@ -0,0 +1,95 @@
+"""Device blueprint models — portable deployment recipes."""
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+from .hardware import HardwareInfo
+from .persisted import PersistedModel
+
+
+_DEFAULT_BLUEPRINT_DIR = Path.home() / ".config" / "redeploy" / "blueprints"
+
+
+class ServicePort(BaseModel):
+    host: int
+    container: int
+    protocol: str = "tcp"
+
+
+class VolumeMount(BaseModel):
+    host: str
+    container: str
+    read_only: bool = False
+
+
+class ServiceSpec(BaseModel):
+    name: str
+    image: str
+    platform: str = ""
+    ports: list[ServicePort] = Field(default_factory=list)
+    volumes: list[VolumeMount] = Field(default_factory=list)
+    env: dict[str, str] = Field(default_factory=dict)
+    command: Optional[str] = None
+    healthcheck: Optional[str] = None
+    depends_on: list[str] = Field(default_factory=list)
+    labels: dict[str, str] = Field(default_factory=dict)
+    restart: str = "unless-stopped"
+    network_mode: Optional[str] = None
+    privileged: bool = False
+    source_ref: Optional[str] = None
+
+
+class HardwareRequirements(BaseModel):
+    arch: str = "linux/arm64"
+    min_ram_mb: int = 0
+    min_disk_gb: int = 0
+    display_type: Optional[str] = None
+    display_resolution: Optional[str] = None
+    i2c_required: bool = False
+    gpio_required: bool = False
+    features: list[str] = Field(default_factory=list)
+
+
+class BlueprintSource(BaseModel):
+    device_id: Optional[str] = None
+    device_name: Optional[str] = None
+    migration_file: Optional[str] = None
+    markpact_files: list[str] = Field(default_factory=list)
+    compose_files: list[str] = Field(default_factory=list)
+    extracted_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+
+
+class DeviceBlueprint(PersistedModel):
+    """Self-contained, portable deployment recipe."""
+    name: str
+    version: str = "0.0.0"
+    description: str = ""
+    tags: list[str] = Field(default_factory=list)
+    created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+
+    services: list[ServiceSpec] = Field(default_factory=list)
+    hardware: HardwareRequirements = Field(default_factory=HardwareRequirements)
+    app_url: Optional[str] = None
+    deploy_strategy: str = "podman_quadlet"
+    env_file: Optional[str] = None
+    notes: str = ""
+    source: BlueprintSource = Field(default_factory=BlueprintSource)
+
+    def service(self, name: str) -> Optional[ServiceSpec]:
+        return next((s for s in self.services if s.name == name), None)
+
+    def save(self, path: Optional[Path] = None) -> Path:
+        p = path or _DEFAULT_BLUEPRINT_DIR / f"{self.name}.blueprint.yaml"
+        p.parent.mkdir(parents=True, exist_ok=True)
+        p.write_text(self.to_yaml())
+        return p
+
+    @classmethod
+    def list_saved(cls) -> list[Path]:
+        if not _DEFAULT_BLUEPRINT_DIR.exists():
+            return []
+        return sorted(_DEFAULT_BLUEPRINT_DIR.glob("*.blueprint.yaml"))

redeploy-0.2.58/redeploy/models/hardware.py

@@ -0,0 +1,117 @@
+"""Hardware models — output of hardware probe."""
+from __future__ import annotations
+
+import re
+from typing import Any, Optional
+
+from pydantic import BaseModel, Field
+
+
+class DrmOutput(BaseModel):
+    """One DRM connector (e.g. card1-DSI-2, card2-HDMI-A-1)."""
+    name: str                           # e.g. "card1-DSI-2"
+    connector: str                      # e.g. "DSI-2", "HDMI-A-1"
+    status: str = "unknown"             # connected / disconnected
+    enabled: str = "unknown"            # enabled / disabled
+    modes: list[str] = Field(default_factory=list)    # e.g. ["1280x800@60"]
+    transform: str = "normal"
+    position: str = "0,0"
+    scale: str = "1.0"
+    edid_bytes: int = 0                 # EDID size in bytes; 0 = no physical panel
+    power_state: Optional[str] = None  # DPMS: "on", "off", "suspend"
+    sysfs_path: str = ""               # e.g. /sys/class/drm/card1-DSI-2
+
+
+class BacklightInfo(BaseModel):
+    """Sysfs backlight device."""
+    name: str                           # e.g. "11-0045"
+    brightness: int = 0
+    max_brightness: int = 255
+    bl_power: int = 0                   # 0=on, 4=off
+    display_name: Optional[str] = None  # e.g. "DSI-2"
+    sysfs_path: str = ""               # e.g. /sys/class/backlight/11-0045
+
+
+class I2CBusInfo(BaseModel):
+    bus: int
+    devices: list[str] = Field(default_factory=list)  # hex addresses found
+    sysfs_path: str = ""               # e.g. /dev/i2c-11
+
+
+class HardwareDiagnostic(BaseModel):
+    """Problem found during hardware probe."""
+    component: str                      # "dsi", "backlight", "i2c", "gpio", "overlay"
+    severity: str = "warning"           # info / warning / error / critical
+    message: str
+    fix: Optional[str] = None          # suggested fix command or action
+
+
+class HardwareInfo(BaseModel):
+    """Hardware state produced by hardware probe."""
+    board: Optional[str] = None         # e.g. "Raspberry Pi 5 Model B Rev 1.0"
+    kernel: Optional[str] = None        # uname -r
+    config_txt: str = ""                # full /boot/firmware/config.txt
+    config_txt_path: str = "/boot/firmware/config.txt"
+
+    # Display
+    drm_outputs: list[DrmOutput] = Field(default_factory=list)
+    backlights: list[BacklightInfo] = Field(default_factory=list)
+    framebuffers: list[str] = Field(default_factory=list)   # /dev/fb* names
+    wlr_outputs: list[dict] = Field(default_factory=list)   # raw wlr-randr output
+
+    # DSI specific
+    dsi_overlays: list[str] = Field(default_factory=list)   # active dtoverlay lines
+    dsi_dmesg: list[str] = Field(default_factory=list)      # relevant dmesg lines
+    dsi_dmesg_errors: list[str] = Field(default_factory=list)
+
+    # I2C
+    i2c_buses: list[I2CBusInfo] = Field(default_factory=list)
+
+    # Kernel modules
+    kernel_modules: list[str] = Field(default_factory=list)  # lsmod filtered
+
+    # Wayland/compositor runtime state
+    wayland_sockets: list[str] = Field(default_factory=list)  # e.g. ["wayland-0"]
+    compositor_processes: dict[str, list[int]] = Field(default_factory=dict)
+
+    # Diagnostics
+    diagnostics: list[HardwareDiagnostic] = Field(default_factory=list)
+
+    @property
+    def has_dsi(self) -> bool:
+        return any("DSI" in o.name for o in self.drm_outputs)
+
+    @property
+    def kms_enabled(self) -> bool:
+        """True if vc4-kms-v3d overlay is present in config.txt."""
+        return any(
+            re.match(r'\s*dtoverlay=vc4-kms-v3d', line)
+            for line in self.config_txt.splitlines()
+            if not line.strip().startswith("#")
+        )
+
+    @property
+    def dsi_connected(self) -> bool:
+        """DRM reports connected — always True on RPi5 when DSI overlay is loaded."""
+        return any("DSI" in o.name and o.status == "connected" for o in self.drm_outputs)
+
+    @property
+    def dsi_physically_connected(self) -> bool:
+        """True only when a physical panel is present (EDID > 0 bytes)."""
+        return any("DSI" in o.name and o.edid_bytes > 0 for o in self.drm_outputs)
+
+    @property
+    def dsi_enabled(self) -> bool:
+        return any("DSI" in o.name and o.enabled == "enabled" for o in self.drm_outputs)
+
+    @property
+    def backlight_on(self) -> bool:
+        return any(b.bl_power == 0 and b.brightness > 0 for b in self.backlights)
+
+    @property
+    def errors(self) -> list[HardwareDiagnostic]:
+        return [d for d in self.diagnostics if d.severity in ("error", "critical")]
+
+    @property
+    def warnings(self) -> list[HardwareDiagnostic]:
+        return [d for d in self.diagnostics if d.severity == "warning"]

redeploy-0.2.58/redeploy/models/infra.py

@@ -0,0 +1,77 @@
+"""Infrastructure state models — output of `detect`."""
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any, Optional
+
+from pydantic import BaseModel, Field
+
+from .enums import ConflictSeverity
+
+
+class ServiceInfo(BaseModel):
+    name: str
+    image: Optional[str] = None
+    status: str = "unknown"
+    version: Optional[str] = None
+    ports: list[int] = Field(default_factory=list)
+    labels: dict[str, str] = Field(default_factory=dict)
+    namespace: Optional[str] = None      # k3s/k8s namespace
+    unit: Optional[str] = None           # systemd unit name
+
+
+class PortInfo(BaseModel):
+    port: int
+    process: str
+    pid: Optional[int] = None
+    via: Optional[str] = None            # "traefik", "nginx", "ingress-nginx"
+    protocol: str = "tcp"
+
+
+class ConflictInfo(BaseModel):
+    type: str                             # "port_steal", "version_mismatch", "duplicate_service"
+    description: str
+    severity: ConflictSeverity = ConflictSeverity.MEDIUM
+    affected: list[str] = Field(default_factory=list)
+    fix_hint: Optional[str] = None
+
+
+class RuntimeInfo(BaseModel):
+    docker: Optional[str] = None
+    docker_compose: Optional[str] = None
+    k3s: Optional[str] = None
+    k3s_namespaces: list[str] = Field(default_factory=list)
+    podman: Optional[str] = None
+    systemd: Optional[str] = None
+    os: Optional[str] = None
+    arch: Optional[str] = None
+    chromium: Optional[str] = None
+
+
+class AppHealthInfo(BaseModel):
+    url: str
+    status_code: Optional[int] = None
+    version: Optional[str] = None
+    healthy: bool = False
+    response_ms: Optional[float] = None
+
+
+class InfraState(BaseModel):
+    """Full detected state of infrastructure — output of `detect`."""
+    host: str                             # "root@1.2.3.4" or "local"
+    app: str = "unknown"
+    scanned_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+
+    runtime: RuntimeInfo = Field(default_factory=RuntimeInfo)
+    ports: dict[int, PortInfo] = Field(default_factory=dict)
+
+    services: dict[str, list[ServiceInfo]] = Field(
+        default_factory=lambda: {"docker": [], "k3s": [], "systemd": [], "podman": []}
+    )
+
+    health: list[AppHealthInfo] = Field(default_factory=list)
+    conflicts: list[ConflictInfo] = Field(default_factory=list)
+    raw: dict[str, Any] = Field(default_factory=dict)    # raw probe output
+
+    detected_strategy: str = "unknown"  # DeployStrategy value
+    current_version: Optional[str] = None

redeploy-0.2.58/redeploy/models/manifest.py

@@ -0,0 +1,151 @@
+"""Project manifest models — redeploy.yaml + environments."""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Optional
+
+import yaml
+from pydantic import BaseModel, Field
+
+from .enums import DeployStrategy
+
+
+class EnvironmentConfig(BaseModel):
+    """One named environment in redeploy.yaml."""
+    host: Optional[str] = None
+    strategy: Optional[str] = None
+    app: Optional[str] = None
+    domain: Optional[str] = None
+    remote_dir: Optional[str] = None
+    env_file: Optional[str] = None
+    ssh_key: Optional[str] = None
+    ssh_port: int = 22
+    verify_url: Optional[str] = None
+    spec: Optional[str] = None
+
+
+class ProjectManifest(BaseModel):
+    """Per-project redeploy.yaml — replaces repetitive Makefile variables."""
+    spec: str = "migration.yaml"
+    local_spec: str = "migration-local.yaml"
+    host: Optional[str] = None
+    app: str = "app"
+    domain: Optional[str] = None
+    ssh_key: Optional[str] = None
+    ssh_port: int = 22
+    remote_dir: Optional[str] = None
+    env_file: str = ".env"
+    environments: dict[str, EnvironmentConfig] = Field(default_factory=dict)
+
+    @classmethod
+    def find_and_load(cls, start: Path) -> Optional[ProjectManifest]:
+        """Walk up from *start* looking for redeploy.css/less/yaml."""
+        for d in [Path(start)] + list(Path(start).parents):
+            for css_name in ("redeploy.css", "redeploy.less"):
+                candidate = d / css_name
+                if candidate.exists():
+                    from ..dsl.loader import load_css
+                    result = load_css(candidate)
+                    if result.manifest:
+                        return result.manifest
+            candidate = d / "redeploy.yaml"
+            if candidate.exists():
+                with candidate.open() as f:
+                    return cls(**yaml.safe_load(f))
+        return None
+
+    @classmethod
+    def find_css(cls, start: Path) -> Optional[Path]:
+        """Return path to redeploy.css/less if found, else None."""
+        for d in [Path(start)] + list(Path(start).parents):
+            for name in ("redeploy.css", "redeploy.less"):
+                p = d / name
+                if p.exists():
+                    return p
+        return None
+
+    def env(self, name: str) -> Optional[EnvironmentConfig]:
+        return self.environments.get(name)
+
+    def resolve_env(self, name: str) -> EnvironmentConfig:
+        base = EnvironmentConfig(
+            host=self.host,
+            app=self.app,
+            domain=self.domain,
+            remote_dir=self.remote_dir,
+            env_file=self.env_file,
+            ssh_key=self.ssh_key,
+            ssh_port=self.ssh_port,
+        )
+        override = self.environments.get(name)
+        if not override:
+            return base
+        return EnvironmentConfig(
+            host=override.host or base.host,
+            strategy=override.strategy,
+            app=override.app or base.app,
+            domain=override.domain or base.domain,
+            remote_dir=override.remote_dir or base.remote_dir,
+            env_file=override.env_file or base.env_file,
+            ssh_key=override.ssh_key or base.ssh_key,
+            ssh_port=override.ssh_port if override.ssh_port != 22 else base.ssh_port,
+            verify_url=override.verify_url,
+            spec=override.spec,
+        )
+
+    @classmethod
+    def from_dotenv(cls, project_dir: Path) -> Optional[ProjectManifest]:
+        """Read DEPLOY_* vars from .env file in project_dir as a fallback."""
+        env_path = Path(project_dir) / ".env"
+        if not env_path.exists():
+            return None
+        data: dict = {}
+        for line in env_path.read_text().splitlines():
+            line = line.strip()
+            if not line or line.startswith("#") or "=" not in line:
+                continue
+            k, _, v = line.partition("=")
+            k = k.strip().upper()
+            v = v.strip().strip('"').strip("'")
+            if k == "DEPLOY_HOST":
+                data["host"] = v
+            elif k == "DEPLOY_APP":
+                data["app"] = v
+            elif k == "DEPLOY_DOMAIN":
+                data["domain"] = v
+            elif k == "DEPLOY_ENV_FILE":
+                data["env_file"] = v
+            elif k == "DEPLOY_SSH_KEY":
+                data["ssh_key"] = v
+        if not data:
+            return None
+        return cls(**data)
+
+    def apply_to_spec(self, spec: Any, env_name: str = "") -> None:
+        """Overlay manifest values onto a MigrationSpec."""
+        from .spec import MigrationSpec
+        assert isinstance(spec, MigrationSpec)
+        cfg = self.resolve_env(env_name) if env_name else self
+        host = cfg.host if isinstance(cfg, EnvironmentConfig) else self.host
+        domain = cfg.domain if isinstance(cfg, EnvironmentConfig) else self.domain
+        remote_dir = cfg.remote_dir if isinstance(cfg, EnvironmentConfig) else self.remote_dir
+        env_file = cfg.env_file if isinstance(cfg, EnvironmentConfig) else self.env_file
+        verify_url = cfg.verify_url if isinstance(cfg, EnvironmentConfig) else None
+        strategy_str = cfg.strategy if isinstance(cfg, EnvironmentConfig) else None
+
+        if host:
+            spec.source.host = host
+            spec.target.host = host
+        if domain and not spec.target.domain:
+            spec.target.domain = domain
+        if remote_dir and not spec.target.remote_dir:
+            spec.target.remote_dir = remote_dir
+        if env_file and not spec.target.env_file:
+            spec.target.env_file = env_file
+        if verify_url and not spec.target.verify_url:
+            spec.target.verify_url = verify_url
+        if strategy_str:
+            try:
+                spec.target.strategy = DeployStrategy(strategy_str)
+            except ValueError:
+                pass

redeploy-0.2.58/redeploy/models/pipeline.py

@@ -0,0 +1,35 @@
+"""Pipeline hook models — generic pre/post/failure lifecycle."""
+from __future__ import annotations
+
+from typing import Literal, Optional
+
+from pydantic import BaseModel
+
+
+PipelinePhase = Literal[
+    "before_plan",
+    "before_apply",
+    "before_step",
+    "after_step",
+    "on_step_failure",
+    "on_step_retry",
+    "after_apply",
+    "on_failure",
+    "always",
+]
+
+
+class Hook(BaseModel):
+    """Generyczny hook w pipeline: faza + akcja + opcjonalny warunek.
+
+    Zastępuje ad-hoc pola typu ``post_deploy``/``pre_deploy``/``insert_before``.
+    Dodatkowe pola specyficzne dla akcji (command, url, ...) idą do ``extra``.
+    """
+    id: str
+    phase: PipelinePhase
+    action: str                                  # StepAction value (ssh_cmd, http_check, local_cmd, ...)
+    description: str = ""
+    when: Optional[str] = None                   # opcjonalny warunek
+    on_failure: Literal["abort", "continue", "warn"] = "warn"
+
+    model_config = {"extra": "allow"}            # zachowuje dodatkowe pola (command, url, ...)