taskfile 0.3.77__tar.gz → 0.3.78__tar.gz

{taskfile-0.3.77/src/taskfile.egg-info → taskfile-0.3.78}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: taskfile
-Version: 0.3.77
+Version: 0.3.78
 Summary: Universal Taskfile runner with multi-environment deploy support. CI/CD agnostic — run locally or from any pipeline.
 Author-email: Tom Sapletta <tom@sapletta.com>
 License-Expression: Apache-2.0

{taskfile-0.3.77 → taskfile-0.3.78}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "taskfile"
-version = "0.3.77"
+version = "0.3.78"
 description = "Universal Taskfile runner with multi-environment deploy support. CI/CD agnostic — run locally or from any pipeline."
 readme = "README.md"
 license = "Apache-2.0"

{taskfile-0.3.77 → taskfile-0.3.78}/src/taskfile/__init__.py

@@ -12,7 +12,7 @@ Features:
     - @remote SSH command execution
 """
 
-__version__ = "0.3.77"
+__version__ = "0.3.78"
 __author__ = "Softreck"
 
 from taskfile.runner import TaskfileRunner

{taskfile-0.3.77 → taskfile-0.3.78}/src/taskfile/deploy_recipes.py

@@ -41,6 +41,7 @@ def expand_deploy_recipe(deploy_section: dict[str, Any], variables: dict[str, st
     health_retries = deploy_section.get("health_retries", 5)
     health_delay = deploy_section.get("health_delay", 5)
     rollback_mode = deploy_section.get("rollback", "manual")  # auto | manual
+    restart_delay = deploy_section.get("restart_delay", 3)  # seconds between stop→start
     tag_var = "${TAG}"
 
     tasks: dict[str, dict] = {}
@@ -111,9 +112,9 @@ def expand_deploy_recipe(deploy_section: dict[str, Any], variables: dict[str, st
     if strategy == "compose":
         tasks["deploy"] = _compose_deploy(deploy_deps)
     elif strategy == "quadlet":
-        tasks["deploy"] = _quadlet_deploy(deploy_deps, images, registry, tag_var)
+        tasks["deploy"] = _quadlet_deploy(deploy_deps, images, registry, tag_var, restart_delay)
     elif strategy == "ssh-push":
-        tasks["deploy"] = _ssh_push_deploy(deploy_deps, images, registry, tag_var)
+        tasks["deploy"] = _ssh_push_deploy(deploy_deps, images, registry, tag_var, restart_delay)
     else:
         tasks["deploy"] = _compose_deploy(deploy_deps)
 
@@ -129,6 +130,16 @@ def expand_deploy_recipe(deploy_section: dict[str, Any], variables: dict[str, st
         ],
     }
 
+    # ── Post-deploy health gate ──
+    tasks["post-deploy"] = {
+        "desc": "Post-deploy health gate — verify all services are healthy after deploy",
+        "tags": ["deploy", "health"],
+        "silent": True,
+        "retries": health_retries,
+        "retry_delay": health_delay,
+        "cmds": _post_deploy_health_cmds(images, health_check, registry, tag_var),
+    }
+
     # ── Rollback ──
     if images:
         rollback_cmds = []
@@ -136,7 +147,9 @@ def expand_deploy_recipe(deploy_section: dict[str, Any], variables: dict[str, st
             image_var = f"{registry}/{svc_name}:{tag_var}"
             rollback_cmds.append(f"@remote podman pull {image_var}")
         for svc_name in images:
-            rollback_cmds.append(f"@remote systemctl --user restart ${{APP_NAME}}-{svc_name}")
+            rollback_cmds.extend(
+                _graceful_restart_cmds(svc_name, restart_delay)
+            )
         tasks["rollback"] = {
             "desc": "Rollback to specified version (--var TAG=<prev>)",
             "tags": ["deploy", "rollback"],
@@ -146,6 +159,38 @@ def expand_deploy_recipe(deploy_section: dict[str, Any], variables: dict[str, st
     return tasks
 
 
+def _graceful_restart_cmds(svc_name: str, restart_delay: int = 3) -> list[str]:
+    """Generate graceful restart commands for a single service.
+
+    Pattern: stop → sleep(delay) → start
+    This avoids the hard restart that causes dropped connections.
+    The delay allows in-flight requests to complete.
+    """
+    return [
+        f"@remote systemctl --user stop ${{APP_NAME}}-{svc_name}",
+        f"sleep {restart_delay}",
+        f"@remote systemctl --user start ${{APP_NAME}}-{svc_name}",
+    ]
+
+
+def _post_deploy_health_cmds(
+    images: dict, health_check: str, registry: str, tag_var: str,
+) -> list[str]:
+    """Generate post-deploy health verification commands."""
+    cmds: list[str] = []
+    # Check each service container is running
+    for svc_name in images:
+        cmds.append(
+            f"@remote systemctl --user is-active --quiet ${{APP_NAME}}-{svc_name} "
+            f"&& echo '{svc_name}: running' || (echo '{svc_name}: NOT RUNNING' && exit 1)"
+        )
+    # Check HTTP health endpoint
+    cmds.append(
+        f"curl -sf https://${{DOMAIN}}{health_check} && echo 'Health: OK' || exit 1"
+    )
+    return cmds
+
+
 def _compose_deploy(deps: list[str]) -> dict:
     """Generate compose-based deploy task."""
     return {
@@ -161,8 +206,11 @@ def _compose_deploy(deps: list[str]) -> dict:
     }
 
 
-def _quadlet_deploy(deps: list[str], images: dict, registry: str, tag_var: str) -> dict:
-    """Generate Quadlet-based deploy task."""
+def _quadlet_deploy(
+    deps: list[str], images: dict, registry: str, tag_var: str,
+    restart_delay: int = 3,
+) -> dict:
+    """Generate Quadlet-based deploy task with graceful restart."""
     cmds = [
         "taskfile quadlet generate",
         "taskfile quadlet upload",
@@ -171,12 +219,13 @@ def _quadlet_deploy(deps: list[str], images: dict, registry: str, tag_var: str)
     for svc_name in images:
         image_var = f"{registry}/{svc_name}:{tag_var}"
         cmds.append(f"@remote podman pull {image_var}")
+    # Graceful restart: stop → delay → start (one service at a time)
     for svc_name in images:
-        cmds.append(f"@remote systemctl --user restart ${{APP_NAME}}-{svc_name}")
+        cmds.extend(_graceful_restart_cmds(svc_name, restart_delay))
     cmds.append("@remote podman image prune -f")
 
     return {
-        "desc": "Deploy via Podman Quadlet (generate → upload → pull → restart)",
+        "desc": "Deploy via Podman Quadlet (generate → upload → pull → graceful restart)",
         "deps": deps,
         "tags": ["ci", "deploy"],
         "retries": 2,
@@ -186,18 +235,22 @@ def _quadlet_deploy(deps: list[str], images: dict, registry: str, tag_var: str)
     }
 
 
-def _ssh_push_deploy(deps: list[str], images: dict, registry: str, tag_var: str) -> dict:
-    """Generate simple SSH pull+restart deploy task."""
+def _ssh_push_deploy(
+    deps: list[str], images: dict, registry: str, tag_var: str,
+    restart_delay: int = 3,
+) -> dict:
+    """Generate simple SSH pull+graceful restart deploy task."""
     cmds = []
     for svc_name in images:
         image_var = f"{registry}/{svc_name}:{tag_var}"
         cmds.append(f"@remote podman pull {image_var}")
+    # Graceful restart: stop → delay → start (one service at a time)
     for svc_name in images:
-        cmds.append(f"@remote systemctl --user restart ${{APP_NAME}}-{svc_name}")
+        cmds.extend(_graceful_restart_cmds(svc_name, restart_delay))
     cmds.append("@remote podman image prune -f")
 
     return {
-        "desc": "Deploy via SSH (pull + restart)",
+        "desc": "Deploy via SSH (pull + graceful restart)",
         "deps": deps,
         "tags": ["ci", "deploy"],
         "retries": 1,

{taskfile-0.3.77 → taskfile-0.3.78}/src/taskfile/diagnostics/__init__.py

@@ -223,8 +223,8 @@ class ProjectDiagnostics:
 
     # ─── Layer 4: Algorithmic fix ───
 
-    def auto_fix(self) -> int:
-        fixed_count = apply_fixes(self._issues)
+    def auto_fix(self, *, interactive: bool = False) -> int:
+        fixed_count = apply_fixes(self._issues, interactive=interactive)
         # Remove fixed issues from legacy list
         fixed_msgs = {i.message for i in self._issues if i.context and i.context.get("_fixed")}
         self.issues = [(m, s, f) for m, s, f in self.issues if m not in fixed_msgs]

{taskfile-0.3.77 → taskfile-0.3.78}/src/taskfile/diagnostics/llm_repair.py

@@ -100,34 +100,6 @@ def classify_runtime_error(
             layer=3,
         )
 
-    # Detect podman/docker pull localhost/ — image not transferred to remote
-    if ("connection refused" in stderr_lower and "localhost" in stderr_lower
-            and ("pull" in cmd.lower() or "pull" in stderr_lower)):
-        # Extract image name from stderr or cmd
-        image = _extract_image_name(cmd, stderr)
-        return Issue(
-            category=IssueCategory.CONFIG_ERROR,
-            message=f"Cannot pull '{image}' — no local registry on remote server",
-            fix_strategy=FixStrategy.MANUAL,
-            severity=SEVERITY_ERROR,
-            fix_description=(
-                f"Images with 'localhost/' prefix must be transferred before deploy.\n"
-                f"  Fix: taskfile push {image}\n"
-                f"  This transfers the image via SSH (docker save | ssh podman load).\n"
-                f"  Then re-run the deploy."
-            ),
-            teach=(
-                "Images prefixed with 'localhost/' are local-only — they exist on your machine "
-                "but not on the remote server. 'podman pull localhost/...' on the remote server "
-                "tries to contact a local registry there, which doesn't exist.\n\n"
-                "**Solution:** Use `taskfile push` to transfer images via SSH before deploying:\n"
-                "```\ntaskfile push myapp-web:latest myapp-landing:latest\n```\n"
-                "This uses `docker save | ssh podman load` — no registry needed."
-            ),
-            context={"cmd": cmd, "stderr": stderr[:500], "image": image},
-            layer=3,
-        )
-
     if "connection refused" in stderr_lower or "no route to host" in stderr_lower:
         return Issue(
             category=IssueCategory.EXTERNAL_ERROR,
@@ -193,24 +165,6 @@ def classify_runtime_error(
     )
 
 
-def _extract_image_name(cmd: str, stderr: str) -> str:
-    """Extract Docker/Podman image name from pull command or stderr."""
-    import re
-    # Try from stderr: "Trying to pull localhost/foo:latest..."
-    m = re.search(r'Trying to pull\s+(\S+)', stderr)
-    if m:
-        return m.group(1).rstrip(".")
-    # Try from stderr: "docker://localhost/foo:latest"
-    m = re.search(r'docker://(\S+?):', stderr)
-    if m:
-        return m.group(1)
-    # Try from cmd: "podman pull IMAGE" or "docker pull IMAGE"
-    m = re.search(r'(?:podman|docker)\s+pull\s+(\S+)', cmd)
-    if m:
-        return m.group(1)
-    return "unknown-image"
-
-
 def _extract_missing_binary(stderr: str) -> str:
     """Extract binary name from 'command not found' stderr."""
     for line in stderr.splitlines():

taskfile-0.3.78/src/taskfile/models/__init__.py

@@ -0,0 +1,29 @@
+"""Data models for Taskfile configuration.
+
+Split into submodules for maintainability:
+    environment.py — Environment, Platform, EnvironmentGroup
+    task.py        — Task, Function, _normalize_commands
+    pipeline.py    — PipelineStage, PipelineConfig
+    config.py      — TaskfileConfig, ComposeConfig
+
+All public symbols are re-exported here for backward compatibility.
+Existing `from taskfile.models import X` imports continue to work.
+"""
+
+from taskfile.models.environment import Environment, Platform, EnvironmentGroup
+from taskfile.models.task import Task, Function, _normalize_commands
+from taskfile.models.pipeline import PipelineStage, PipelineConfig
+from taskfile.models.config import TaskfileConfig, ComposeConfig
+
+__all__ = [
+    "Environment",
+    "Platform",
+    "EnvironmentGroup",
+    "Task",
+    "Function",
+    "_normalize_commands",
+    "PipelineStage",
+    "PipelineConfig",
+    "TaskfileConfig",
+    "ComposeConfig",
+]

taskfile-0.3.77/src/taskfile/models.py → taskfile-0.3.78/src/taskfile/models/config.py

@@ -1,111 +1,13 @@
-"""Data models for Taskfile configuration."""
+"""TaskfileConfig and ComposeConfig — main configuration container."""
 
 from __future__ import annotations
 
-import os
 from dataclasses import dataclass, field
 from typing import Any
 
-
-@dataclass
-class Environment:
-    """Deployment environment configuration."""
-
-    name: str
-    variables: dict[str, str] = field(default_factory=dict)
-    ssh_host: str | None = None
-    ssh_user: str = "deploy"
-    ssh_port: int = 22
-    ssh_key: str | None = None
-    container_runtime: str = "docker"  # docker | podman
-    compose_command: str = "docker compose"  # docker compose | podman-compose
-    service_manager: str = "compose"  # compose | quadlet | systemd
-    env_file: str | None = None  # .env.local, .env.prod
-    compose_file: str = "docker-compose.yml"  # source compose file
-    quadlet_dir: str = "deploy/quadlet"  # local dir for generated .container files
-    quadlet_remote_dir: str = "~/.config/containers/systemd"  # remote dir for Quadlet
-
-    @property
-    def ssh_target(self) -> str | None:
-        if not self.ssh_host:
-            return None
-        return f"{self.ssh_user}@{self.ssh_host}"
-
-    @property
-    def ssh_opts(self) -> str:
-        parts = [f"-p {self.ssh_port}"]
-        if self.ssh_key:
-            key_path = os.path.expanduser(self.ssh_key)
-            parts.append(f"-i {key_path}")
-        parts.append("-o StrictHostKeyChecking=accept-new")
-        return " ".join(parts)
-
-    @property
-    def scp_opts(self) -> str:
-        """SCP options — uses -P (uppercase) for port, unlike ssh's -p."""
-        parts = [f"-P {self.ssh_port}"]
-        if self.ssh_key:
-            key_path = os.path.expanduser(self.ssh_key)
-            parts.append(f"-i {key_path}")
-        parts.append("-o StrictHostKeyChecking=accept-new")
-        return " ".join(parts)
-
-    @property
-    def is_remote(self) -> bool:
-        return self.ssh_host is not None
-
-    def resolve_variables(self, global_vars: dict[str, str], dotenv_vars: dict[str, str] | None = None) -> dict[str, str]:
-        """Merge global variables with environment-specific ones.
-        Environment variables override global ones.
-        CLI --var overrides are applied separately in the runner.
-
-        Priority (highest wins): env-specific vars > global vars > dotenv.
-        Dotenv only fills in values that still contain ${VAR} patterns.
-        """
-        merged = {**global_vars, **self.variables}
-        resolved = {}
-        env_source = dotenv_vars if dotenv_vars is not None else os.environ
-        for key, value in merged.items():
-            # Only use dotenv to fill values containing ${...} or when value is empty
-            if isinstance(value, str) and ("${" in value or "$" in value or value == ""):
-                resolved[key] = env_source.get(key, value)
-            else:
-                resolved[key] = value
-        return resolved
-
-
-@dataclass
-class Platform:
-    """Target platform configuration (e.g. desktop, web, mobile)."""
-
-    name: str
-    variables: dict[str, str] = field(default_factory=dict)
-    build_cmd: str | None = None
-    deploy_cmd: str | None = None
-    description: str = ""
-
-    def resolve_variables(self, global_vars: dict[str, str], dotenv_vars: dict[str, str] | None = None) -> dict[str, str]:
-        """Merge global variables with platform-specific ones.
-        Platform variables override global ones.
-        """
-        merged = {**global_vars, **self.variables}
-        resolved = {}
-        # Use dotenv_vars if provided, otherwise fall back to os.environ
-        env_source = dotenv_vars if dotenv_vars is not None else os.environ
-        for key, value in merged.items():
-            resolved[key] = env_source.get(key, value)
-        return resolved
-
-
-@dataclass
-class EnvironmentGroup:
-    """Group of environments sharing an update strategy (e.g. RPi fleet)."""
-
-    name: str
-    members: list[str] = field(default_factory=list)
-    strategy: str = "parallel"  # rolling | parallel | canary
-    max_parallel: int = 5
-    canary_count: int = 1
+from taskfile.models.environment import Environment, Platform, EnvironmentGroup
+from taskfile.models.task import Task, Function, _normalize_commands
+from taskfile.models.pipeline import PipelineStage, PipelineConfig
 
 
 @dataclass
@@ -118,141 +20,6 @@ class ComposeConfig:
     auto_update: bool = True
 
 
-@dataclass
-class Function:
-    """Embedded function callable from tasks via @fn prefix."""
-
-    name: str
-    lang: str = "shell"  # shell | python | node | binary
-    code: str | None = None  # inline code
-    file: str | None = None  # external file path
-    function: str | None = None  # specific function to call (Python)
-    description: str = ""
-
-
-@dataclass
-class Task:
-    """Single task definition."""
-
-    name: str
-    description: str = ""
-    commands: list[str] = field(default_factory=list)
-    script: str | None = None  # external script file path (alternative to inline cmds)
-    deps: list[str] = field(default_factory=list)
-    env_filter: list[str] | None = None
-    platform_filter: list[str] | None = None
-    working_dir: str | None = None
-    silent: bool = False
-    ignore_errors: bool = False
-    condition: str | None = None
-    stage: str | None = None  # pipeline stage this task belongs to
-    parallel: bool = False  # run deps in parallel (concurrent execution)
-    retries: int = 0  # retry count on failure (Ansible-inspired)
-    retry_delay: int = 1  # seconds between retries
-    timeout: int = 0  # command timeout in seconds (0 = no timeout)
-    tags: list[str] = field(default_factory=list)  # tags for selective execution
-    register: str | None = None  # capture stdout into this variable name
-
-    def should_run_on(self, env_name: str) -> bool:
-        if self.env_filter is None:
-            return True
-        return env_name in self.env_filter
-
-    def should_run_on_platform(self, platform_name: str | None) -> bool:
-        if self.platform_filter is None:
-            return True
-        if platform_name is None:
-            return True
-        return platform_name in self.platform_filter
-
-
-@dataclass
-class PipelineStage:
-    """A stage in the CI/CD pipeline."""
-
-    name: str
-    tasks: list[str] = field(default_factory=list)
-    env: str | None = None  # override environment for this stage
-    when: str = "auto"  # auto | manual | tag | branch:main
-    runner: str | None = None  # override runner image
-    docker_in_docker: bool = False
-    artifacts: list[str] = field(default_factory=list)
-    cache: list[str] = field(default_factory=list)
-
-
-@dataclass
-class PipelineConfig:
-    """CI/CD pipeline configuration."""
-
-    stages: list[PipelineStage] = field(default_factory=list)
-    python_version: str = "3.12"
-    runner_image: str = "ubuntu-latest"
-    docker_in_docker: bool = False
-    cache: list[str] = field(default_factory=list)
-    artifacts: list[str] = field(default_factory=list)
-    secrets: list[str] = field(default_factory=list)
-    branches: list[str] = field(default_factory=lambda: ["main"])
-    install_cmd: str = "pip install taskfile"
-
-    @classmethod
-    def from_dict(cls, data: dict[str, Any]) -> PipelineConfig:
-        config = cls(
-            python_version=str(data.get("python_version", "3.12")),
-            runner_image=data.get("runner_image", "ubuntu-latest"),
-            docker_in_docker=data.get("docker_in_docker", False),
-            cache=data.get("cache", []),
-            artifacts=data.get("artifacts", []),
-            secrets=data.get("secrets", []),
-            branches=data.get("branches", ["main"]),
-            install_cmd=data.get("install_cmd", "pip install taskfile"),
-        )
-        for stage_data in data.get("stages", []):
-            if isinstance(stage_data, dict):
-                config.stages.append(PipelineStage(
-                    name=stage_data.get("name", ""),
-                    tasks=stage_data.get("tasks", []),
-                    env=stage_data.get("env"),
-                    when=stage_data.get("when", "auto"),
-                    runner=stage_data.get("runner"),
-                    docker_in_docker=stage_data.get("docker_in_docker", False),
-                    artifacts=stage_data.get("artifacts", []),
-                    cache=stage_data.get("cache", []),
-                ))
-            elif isinstance(stage_data, str):
-                # Shorthand: stage name = task name
-                config.stages.append(PipelineStage(
-                    name=stage_data, tasks=[stage_data],
-                ))
-        return config
-
-    def infer_from_tasks(self, tasks: dict[str, "Task"]) -> None:
-        """Auto-generate pipeline stages from task 'stage' fields if no stages defined."""
-        if self.stages:
-            return
-        stage_map: dict[str, list[str]] = {}
-        for task_name, task in tasks.items():
-            if task.stage:
-                stage_map.setdefault(task.stage, []).append(task_name)
-        # Preserve insertion order
-        for stage_name, task_names in stage_map.items():
-            self.stages.append(PipelineStage(name=stage_name, tasks=task_names))
-
-
-def _normalize_commands(cmds: list) -> list[str]:
-    """Normalize commands list — YAML can misparse 'echo key: value' as dicts."""
-    result = []
-    for item in cmds:
-        if isinstance(item, str):
-            result.append(item)
-        elif isinstance(item, dict):
-            # YAML misparse: {'echo "  App': 'http://...'} → reconstruct
-            for k, v in item.items():
-                result.append(f"{k}: {v}" if v else str(k))
-        else:
-            result.append(str(item))
-    return result
-
-
 @dataclass
 class TaskfileConfig:
     """Parsed Taskfile configuration."""

taskfile-0.3.78/src/taskfile/models/environment.py

@@ -0,0 +1,107 @@
+"""Environment, Platform, and EnvironmentGroup data models."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+
+
+@dataclass
+class Environment:
+    """Deployment environment configuration."""
+
+    name: str
+    variables: dict[str, str] = field(default_factory=dict)
+    ssh_host: str | None = None
+    ssh_user: str = "deploy"
+    ssh_port: int = 22
+    ssh_key: str | None = None
+    container_runtime: str = "docker"  # docker | podman
+    compose_command: str = "docker compose"  # docker compose | podman-compose
+    service_manager: str = "compose"  # compose | quadlet | systemd
+    env_file: str | None = None  # .env.local, .env.prod
+    compose_file: str = "docker-compose.yml"  # source compose file
+    quadlet_dir: str = "deploy/quadlet"  # local dir for generated .container files
+    quadlet_remote_dir: str = "~/.config/containers/systemd"  # remote dir for Quadlet
+
+    @property
+    def ssh_target(self) -> str | None:
+        if not self.ssh_host:
+            return None
+        return f"{self.ssh_user}@{self.ssh_host}"
+
+    @property
+    def ssh_opts(self) -> str:
+        parts = [f"-p {self.ssh_port}"]
+        if self.ssh_key:
+            key_path = os.path.expanduser(self.ssh_key)
+            parts.append(f"-i {key_path}")
+        parts.append("-o StrictHostKeyChecking=accept-new")
+        return " ".join(parts)
+
+    @property
+    def scp_opts(self) -> str:
+        """SCP options — uses -P (uppercase) for port, unlike ssh's -p."""
+        parts = [f"-P {self.ssh_port}"]
+        if self.ssh_key:
+            key_path = os.path.expanduser(self.ssh_key)
+            parts.append(f"-i {key_path}")
+        parts.append("-o StrictHostKeyChecking=accept-new")
+        return " ".join(parts)
+
+    @property
+    def is_remote(self) -> bool:
+        return self.ssh_host is not None
+
+    def resolve_variables(self, global_vars: dict[str, str], dotenv_vars: dict[str, str] | None = None) -> dict[str, str]:
+        """Merge global variables with environment-specific ones.
+        Environment variables override global ones.
+        CLI --var overrides are applied separately in the runner.
+
+        Priority (highest wins): env-specific vars > global vars > dotenv.
+        Dotenv only fills in values that still contain ${VAR} patterns.
+        """
+        merged = {**global_vars, **self.variables}
+        resolved = {}
+        env_source = dotenv_vars if dotenv_vars is not None else os.environ
+        for key, value in merged.items():
+            # Only use dotenv to fill values containing ${...} or when value is empty
+            if isinstance(value, str) and ("${" in value or "$" in value or value == ""):
+                resolved[key] = env_source.get(key, value)
+            else:
+                resolved[key] = value
+        return resolved
+
+
+@dataclass
+class Platform:
+    """Target platform configuration (e.g. desktop, web, mobile)."""
+
+    name: str
+    variables: dict[str, str] = field(default_factory=dict)
+    build_cmd: str | None = None
+    deploy_cmd: str | None = None
+    description: str = ""
+
+    def resolve_variables(self, global_vars: dict[str, str], dotenv_vars: dict[str, str] | None = None) -> dict[str, str]:
+        """Merge global variables with platform-specific ones.
+        Platform variables override global ones.
+        """
+        merged = {**global_vars, **self.variables}
+        resolved = {}
+        # Use dotenv_vars if provided, otherwise fall back to os.environ
+        env_source = dotenv_vars if dotenv_vars is not None else os.environ
+        for key, value in merged.items():
+            resolved[key] = env_source.get(key, value)
+        return resolved
+
+
+@dataclass
+class EnvironmentGroup:
+    """Group of environments sharing an update strategy (e.g. RPi fleet)."""
+
+    name: str
+    members: list[str] = field(default_factory=list)
+    strategy: str = "parallel"  # rolling | parallel | canary
+    max_parallel: int = 5
+    canary_count: int = 1