@mriekki/project-forge 0.0.0-stage → 2.0.0

package/assets/generated/deployment/src/project_forge_deployment/box_platform.py

@@ -0,0 +1,208 @@
+"""Shared Ubuntu box platform ownership and lifecycle operations."""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import shlex
+import subprocess
+from typing import Any
+
+from .box_platform_assets import (
+    AVAHI_SERVICE,
+    CADDYFILE,
+    CADDY_CONTAINER,
+    CADDY_IMAGE,
+    COMPOSE_YAML,
+    HOST_PLATFORM_WRITE_PHRASE,
+    NETWORK_NAME,
+    PLATFORM_DISTRIBUTION,
+    PLATFORM_ROOT,
+    PLATFORM_SCHEMA_VERSION,
+    PLATFORM_VERSION,
+    PUBLISH_ALIAS_SH,
+)
+from .box_platform_remote import REMOTE_SCRIPT
+from .errors import DeploymentKitError
+from .profiles import load_profile
+from .ssh import ssh_args, verify_access
+
+_BOOL_KEYS = {
+    "markerPresent",
+    "prerequisitesReady",
+    "networkPresent",
+    "caddyRunning",
+    "avahiRunning",
+    "port80InUse",
+}
+_EXPECTED_KEYS = {
+    "state",
+    "markerPresent",
+    "markerSchemaVersion",
+    "markerDistribution",
+    "markerPlatformVersion",
+    "expectedPlatformVersion",
+    "prerequisitesReady",
+    "networkPresent",
+    "caddyRunning",
+    "avahiRunning",
+    "port80InUse",
+    "platformRoot",
+    "networkName",
+    "caddyContainer",
+}
+
+
+def build_remote_script() -> str:
+    replacements = {
+        "__PLATFORM_ROOT__": PLATFORM_ROOT,
+        "__NETWORK_NAME__": NETWORK_NAME,
+        "__CADDY_CONTAINER__": CADDY_CONTAINER,
+        "__CADDY_IMAGE__": CADDY_IMAGE,
+        "__SCHEMA_VERSION__": str(PLATFORM_SCHEMA_VERSION),
+        "__PLATFORM_VERSION__": PLATFORM_VERSION,
+        "__DISTRIBUTION__": PLATFORM_DISTRIBUTION,
+        "__COMPOSE_B64__": base64.b64encode(COMPOSE_YAML.encode()).decode("ascii"),
+        "__CADDYFILE_B64__": base64.b64encode(CADDYFILE.encode()).decode("ascii"),
+        "__PUBLISH_ALIAS_B64__": base64.b64encode(PUBLISH_ALIAS_SH.encode()).decode("ascii"),
+        "__AVAHI_SERVICE_B64__": base64.b64encode(AVAHI_SERVICE.encode()).decode("ascii"),
+    }
+    script = REMOTE_SCRIPT
+    for placeholder, value in replacements.items():
+        script = script.replace(placeholder, value)
+    if "__" in script:
+        raise DeploymentKitError("Internal host-platform script contains an unresolved placeholder.")
+    return script
+
+
+def _parse_status(output: str) -> dict[str, Any]:
+    result: dict[str, Any] = {}
+    for raw in output.splitlines():
+        if not raw.strip():
+            continue
+        if "=" not in raw:
+            raise DeploymentKitError(f"Malformed host-platform status line: {raw!r}")
+        key, value = raw.split("=", 1)
+        if key not in _EXPECTED_KEYS or key in result:
+            raise DeploymentKitError(f"Unexpected or duplicate host-platform status key: {key!r}")
+        if key in _BOOL_KEYS:
+            if value not in {"true", "false"}:
+                raise DeploymentKitError(f"Invalid boolean host-platform status value for {key}.")
+            result[key] = value == "true"
+        else:
+            result[key] = value
+    missing = _EXPECTED_KEYS - result.keys()
+    if missing:
+        raise DeploymentKitError(
+            "Host-platform status omitted required keys: " + ", ".join(sorted(missing))
+        )
+    return result
+
+
+def _run_remote(profile: dict[str, Any], address: str, action: str, *, sudo: bool) -> str:
+    if action not in {"status", "install", "upgrade"}:
+        raise DeploymentKitError(f"Unsupported host-platform action: {action}")
+    remote_command = "bash -s -- " + shlex.quote(action)
+    if sudo:
+        remote_command = "sudo -n " + remote_command
+    command = ssh_args(profile, address, command=remote_command)
+    completed = subprocess.run(
+        command,
+        input=build_remote_script().encode("utf-8"),
+        check=False,
+        capture_output=True,
+    )
+    stdout = completed.stdout.decode("utf-8", errors="replace")
+    stderr = completed.stderr.decode("utf-8", errors="replace")
+    if completed.returncode != 0:
+        detail = stderr.strip() or stdout.strip() or f"exit {completed.returncode}"
+        raise DeploymentKitError(f"Remote host-platform {action} failed: {detail}")
+    return stdout
+
+
+def platform_status(name: str) -> dict[str, Any]:
+    profile = load_profile(name)
+    evidence = verify_access(profile)
+    status = _parse_status(_run_remote(profile, evidence["address"], "status", sudo=True))
+    status["targetName"] = name
+    status["verifiedAddress"] = evidence["address"]
+    return status
+
+
+def platform_doctor(name: str) -> dict[str, Any]:
+    status = platform_status(name)
+    next_actions = {
+        "installable": "platform-install",
+        "upgrade-required": "platform-upgrade",
+        "drifted": "inspect-platform-drift",
+        "blocked": "prepare-host-prerequisites",
+        "blocked-port-80": "identify-existing-port-80-owner",
+        "incompatible": "manual-platform-recovery",
+        "ready": "none",
+    }
+    status["nextAction"] = next_actions.get(status["state"], "manual-review")
+    status["mutated"] = False
+    return status
+
+
+def _snapshot(status: dict[str, Any]) -> str:
+    selected = {key: status[key] for key in sorted(_EXPECTED_KEYS)}
+    return hashlib.sha256(json.dumps(selected, sort_keys=True, separators=(",", ":")).encode()).hexdigest()
+
+
+def plan_platform_change(name: str, action: str) -> dict[str, Any]:
+    if action not in {"install", "upgrade"}:
+        raise DeploymentKitError("Platform change action must be install or upgrade.")
+    status = platform_status(name)
+    expected_state = "installable" if action == "install" else "upgrade-required"
+    if status["state"] != expected_state:
+        raise DeploymentKitError(
+            f"Platform {action} requires state '{expected_state}', but target '{name}' is '{status['state']}'."
+        )
+    return {
+        "targetName": name,
+        "action": action,
+        "fromState": status["state"],
+        "toPlatformVersion": PLATFORM_VERSION,
+        "distribution": PLATFORM_DISTRIBUTION,
+        "platformRoot": PLATFORM_ROOT,
+        "preserves": ["route-conf.d", "route-registry", "caddy-data", "caddy-config", "shared-network"],
+        "doesNotOwn": ["application-containers", "application-data", "application-routes"],
+        "statusSnapshot": _snapshot(status),
+    }
+
+
+def apply_platform_change(plan: dict[str, Any]) -> dict[str, Any]:
+    required = {
+        "targetName",
+        "action",
+        "fromState",
+        "toPlatformVersion",
+        "distribution",
+        "platformRoot",
+        "preserves",
+        "doesNotOwn",
+        "statusSnapshot",
+    }
+    if not isinstance(plan, dict) or set(plan) != required:
+        raise DeploymentKitError("Malformed host-platform change plan.")
+    name = plan["targetName"]
+    action = plan["action"]
+    if action not in {"install", "upgrade"}:
+        raise DeploymentKitError("Malformed host-platform change action.")
+    current = platform_status(name)
+    if _snapshot(current) != plan["statusSnapshot"]:
+        raise DeploymentKitError(
+            "Host-platform state changed after the plan was reviewed; create and authorize a fresh plan."
+        )
+    profile = load_profile(name)
+    evidence = verify_access(profile)
+    _run_remote(profile, evidence["address"], action, sudo=True)
+    final = platform_status(name)
+    if final["state"] != "ready":
+        raise DeploymentKitError(
+            f"Host-platform {action} completed but readiness is '{final['state']}', not 'ready'."
+        )
+    final["mutated"] = True
+    return final

package/assets/generated/deployment/src/project_forge_deployment/box_platform_assets.py

@@ -0,0 +1,100 @@
+"""Static shared-box platform assets and contract constants."""
+
+PLATFORM_SCHEMA_VERSION = 1
+PLATFORM_VERSION = "2"
+PLATFORM_DISTRIBUTION = "trusted-lan-ubuntu-compose"
+PLATFORM_ROOT = "/srv/project-forge-platform"
+NETWORK_NAME = "caddy-net"
+CADDY_CONTAINER = "project-forge-caddy"
+CADDY_IMAGE = "caddy:2.8.4-alpine@sha256:af32e97399febea808609119bb21544d0265c58a02836576e32a2d082c262c17"
+HOST_PLATFORM_WRITE_PHRASE = "[HOST PLATFORM WRITE]"
+
+COMPOSE_YAML = f"""services:
+  caddy:
+    image: {CADDY_IMAGE}
+    container_name: {CADDY_CONTAINER}
+    restart: unless-stopped
+    ports:
+      - \"80:80\"
+    volumes:
+      - {PLATFORM_ROOT}/proxy/Caddyfile:/etc/caddy/Caddyfile:ro
+      - {PLATFORM_ROOT}/proxy/conf.d:/etc/caddy/conf.d:ro
+      - {PLATFORM_ROOT}/proxy/data:/data
+      - {PLATFORM_ROOT}/proxy/config:/config
+    networks:
+      - {NETWORK_NAME}
+    logging:
+      driver: json-file
+      options:
+        max-size: \"10m\"
+        max-file: \"3\"
+
+networks:
+  {NETWORK_NAME}:
+    external: true
+"""
+
+CADDYFILE = """{
+    auto_https off
+}
+
+import /etc/caddy/conf.d/*.caddy
+"""
+
+PUBLISH_ALIAS_SH = """#!/usr/bin/env bash
+set -Eeuo pipefail
+
+: \"${ALIAS_HOSTNAME:?ALIAS_HOSTNAME is required}\"
+
+current_ip() {
+    local ip
+    ip=\"$(ip route get 1.1.1.1 2>/dev/null | awk '{for(i=1;i<=NF;i++) if($i==\"src\") print $(i+1)}')\"
+    if [[ -z \"$ip\" ]]; then
+        ip=\"$(ip -4 addr show scope global | grep -v 'docker' | grep -v 'br-' | awk '/inet / {print $2}' | cut -d/ -f1 | head -n1)\"
+    fi
+    printf '%s\\n' \"$ip\"
+}
+
+CURRENT_IP=\"$(current_ip)\"
+if [[ -z \"$CURRENT_IP\" ]]; then
+    echo \"project-forge alias publisher: could not determine host LAN IPv4 address.\" >&2
+    exit 1
+fi
+
+/usr/bin/avahi-publish -a -R \"$ALIAS_HOSTNAME\" \"$CURRENT_IP\" &
+AVAHI_PID=$!
+
+cleanup() {
+    kill \"$AVAHI_PID\" 2>/dev/null || true
+    wait \"$AVAHI_PID\" 2>/dev/null || true
+}
+trap cleanup SIGTERM SIGINT EXIT
+
+while kill -0 \"$AVAHI_PID\" 2>/dev/null; do
+    sleep 10
+    NEW_IP=\"$(current_ip)\"
+    if [[ -n \"$NEW_IP\" && \"$NEW_IP\" != \"$CURRENT_IP\" ]]; then
+        cleanup
+        exit 0
+    fi
+done
+wait \"$AVAHI_PID\"
+"""
+
+AVAHI_SERVICE = """[Unit]
+Description=Project Forge mDNS alias %i
+After=network-online.target avahi-daemon.service
+Wants=network-online.target
+Requires=avahi-daemon.service
+
+[Service]
+Type=simple
+EnvironmentFile=/etc/project-forge-platform/aliases/%i.env
+ExecStart=/usr/local/lib/project-forge-platform/publish-alias.sh
+Restart=always
+RestartSec=2
+NoNewPrivileges=true
+
+[Install]
+WantedBy=multi-user.target
+"""

package/assets/generated/deployment/src/project_forge_deployment/box_platform_remote.py

@@ -0,0 +1,271 @@
+"""Remote Ubuntu host-platform script template."""
+
+REMOTE_SCRIPT = r'''#!/usr/bin/env bash
+set -Eeuo pipefail
+
+ACTION="$1"
+PLATFORM_ROOT="__PLATFORM_ROOT__"
+PROXY_ROOT="$PLATFORM_ROOT/proxy"
+ROUTE_ROOT="$PLATFORM_ROOT/routes"
+MARKER="$PLATFORM_ROOT/platform.env"
+LOCK_FILE="/run/lock/project-forge-platform.lock"
+NETWORK_NAME="__NETWORK_NAME__"
+CADDY_CONTAINER="__CADDY_CONTAINER__"
+CADDY_IMAGE="__CADDY_IMAGE__"
+SCHEMA_VERSION="__SCHEMA_VERSION__"
+PLATFORM_VERSION="__PLATFORM_VERSION__"
+DISTRIBUTION="__DISTRIBUTION__"
+COMPOSE_B64="__COMPOSE_B64__"
+CADDYFILE_B64="__CADDYFILE_B64__"
+PUBLISH_ALIAS_B64="__PUBLISH_ALIAS_B64__"
+AVAHI_SERVICE_B64="__AVAHI_SERVICE_B64__"
+
+marker_value() {
+    local key="$1"
+    [[ -f "$MARKER" ]] || return 1
+    sed -n "s/^${key}=//p" "$MARKER" | head -n1
+}
+port80_in_use() {
+    if command -v ss >/dev/null 2>&1; then
+        ss -ltn '( sport = :80 )' 2>/dev/null | tail -n +2 | grep -q .
+    else
+        return 1
+    fi
+}
+prereqs_ready() {
+    command -v docker >/dev/null 2>&1 &&
+    docker compose version >/dev/null 2>&1 &&
+    command -v systemctl >/dev/null 2>&1 &&
+    command -v avahi-publish >/dev/null 2>&1 &&
+    command -v flock >/dev/null 2>&1 &&
+    command -v base64 >/dev/null 2>&1 &&
+    command -v install >/dev/null 2>&1 &&
+    command -v mktemp >/dev/null 2>&1 &&
+    command -v ss >/dev/null 2>&1
+}
+
+status() {
+    local marker_present=false prereqs=false network=false caddy_running=false avahi=false port80=false
+    [[ -f "$MARKER" ]] && marker_present=true
+    prereqs_ready && prereqs=true || true
+    docker network inspect "$NETWORK_NAME" >/dev/null 2>&1 && network=true || true
+    [[ "$(docker inspect --format '{{.State.Status}}' "$CADDY_CONTAINER" 2>/dev/null || true)" == "running" ]] && caddy_running=true || true
+    systemctl is-active --quiet avahi-daemon 2>/dev/null && avahi=true || true
+    port80_in_use && port80=true || true
+
+    local state marker_schema marker_distribution marker_version
+    marker_schema="$(marker_value SCHEMA_VERSION 2>/dev/null || true)"
+    marker_distribution="$(marker_value DISTRIBUTION 2>/dev/null || true)"
+    marker_version="$(marker_value PLATFORM_VERSION 2>/dev/null || true)"
+
+    if [[ "$marker_present" == false ]]; then
+        if [[ "$prereqs" != true ]]; then
+            state="blocked"
+        elif [[ "$port80" == true ]]; then
+            state="blocked-port-80"
+        else
+            state="installable"
+        fi
+    elif [[ "$marker_schema" != "$SCHEMA_VERSION" || "$marker_distribution" != "$DISTRIBUTION" ]]; then
+        state="incompatible"
+    elif [[ "$prereqs" != true ]]; then
+        state="blocked"
+    elif [[ "$marker_version" != "$PLATFORM_VERSION" ]]; then
+        state="upgrade-required"
+    elif [[ "$network" == true && "$caddy_running" == true && "$avahi" == true && -f "$PROXY_ROOT/compose.yaml" && -f "$PROXY_ROOT/Caddyfile" && -d "$ROUTE_ROOT" && -f /usr/local/lib/project-forge-platform/publish-alias.sh && -f /etc/systemd/system/project-forge-avahi-alias@.service ]]; then
+        state="ready"
+    else
+        state="drifted"
+    fi
+
+    printf 'state=%s\n' "$state"
+    printf 'markerPresent=%s\n' "$marker_present"
+    printf 'markerSchemaVersion=%s\n' "$marker_schema"
+    printf 'markerDistribution=%s\n' "$marker_distribution"
+    printf 'markerPlatformVersion=%s\n' "$marker_version"
+    printf 'expectedPlatformVersion=%s\n' "$PLATFORM_VERSION"
+    printf 'prerequisitesReady=%s\n' "$prereqs"
+    printf 'networkPresent=%s\n' "$network"
+    printf 'caddyRunning=%s\n' "$caddy_running"
+    printf 'avahiRunning=%s\n' "$avahi"
+    printf 'port80InUse=%s\n' "$port80"
+    printf 'platformRoot=%s\n' "$PLATFORM_ROOT"
+    printf 'networkName=%s\n' "$NETWORK_NAME"
+    printf 'caddyContainer=%s\n' "$CADDY_CONTAINER"
+}
+
+require_write_prereqs() {
+    if ! prereqs_ready; then
+        echo "Required host prerequisites are missing. Docker Engine + Compose, systemd, avahi-utils, iproute2/ss, flock, base64, install, and mktemp must be prepared separately." >&2
+        exit 3
+    fi
+}
+
+write_marker() {
+    local tmp="$MARKER.tmp.$$"
+    cat > "$tmp" <<EOF
+SCHEMA_VERSION=$SCHEMA_VERSION
+DISTRIBUTION=$DISTRIBUTION
+PLATFORM_VERSION=$PLATFORM_VERSION
+NETWORK_NAME=$NETWORK_NAME
+CADDY_CONTAINER=$CADDY_CONTAINER
+CADDY_IMAGE=$CADDY_IMAGE
+EOF
+    chmod 0644 "$tmp"
+    mv -f "$tmp" "$MARKER"
+}
+
+decode_to() {
+    local payload="$1" dest="$2" mode="$3"
+    local tmp="${dest}.tmp.$$"
+    printf '%s' "$payload" | base64 --decode > "$tmp"
+    chmod "$mode" "$tmp"
+    mv -f "$tmp" "$dest"
+}
+
+validate_candidate() {
+    local candidate_compose="$1" candidate_caddy="$2"
+    docker compose -f "$candidate_compose" config >/dev/null
+    docker run --rm \
+        -v "$candidate_caddy:/etc/caddy/Caddyfile:ro" \
+        -v "$PROXY_ROOT/conf.d:/etc/caddy/conf.d:ro" \
+        "$CADDY_IMAGE" caddy validate --config /etc/caddy/Caddyfile >/dev/null
+}
+
+install_platform() {
+    require_write_prereqs
+    if [[ -f "$MARKER" ]]; then
+        echo "Platform marker already exists; use explicit upgrade instead of install." >&2
+        exit 4
+    fi
+    if port80_in_use; then
+        echo "Port 80 is already occupied; prepare a clean host before platform install." >&2
+        exit 6
+    fi
+
+    install -d -m 0750 "$PLATFORM_ROOT" "$PROXY_ROOT" "$ROUTE_ROOT"
+    install -d -m 0755 "$PROXY_ROOT/conf.d" "$PROXY_ROOT/data" "$PROXY_ROOT/config"
+    install -d -m 0750 "$ROUTE_ROOT"
+    install -d -m 0755 /usr/local/lib/project-forge-platform /etc/project-forge-platform/aliases
+    if [[ ! -e "$PROXY_ROOT/conf.d/00-platform-empty.caddy" ]]; then
+        printf '# Platform-owned placeholder; application routes are registered separately.\n' > "$PROXY_ROOT/conf.d/00-platform-empty.caddy"
+        chmod 0644 "$PROXY_ROOT/conf.d/00-platform-empty.caddy"
+    fi
+
+    if ! docker network inspect "$NETWORK_NAME" >/dev/null 2>&1; then
+        docker network create "$NETWORK_NAME" >/dev/null
+    fi
+
+    local candidate_dir candidate_compose candidate_caddy
+    candidate_dir="$(mktemp -d)"
+    trap 'rm -rf "$candidate_dir"' RETURN
+    candidate_compose="$candidate_dir/compose.yaml"
+    candidate_caddy="$candidate_dir/Caddyfile"
+    printf '%s' "$COMPOSE_B64" | base64 --decode > "$candidate_compose"
+    printf '%s' "$CADDYFILE_B64" | base64 --decode > "$candidate_caddy"
+    validate_candidate "$candidate_compose" "$candidate_caddy"
+
+    decode_to "$COMPOSE_B64" "$PROXY_ROOT/compose.yaml" 0644
+    decode_to "$CADDYFILE_B64" "$PROXY_ROOT/Caddyfile" 0644
+    decode_to "$PUBLISH_ALIAS_B64" /usr/local/lib/project-forge-platform/publish-alias.sh 0755
+    decode_to "$AVAHI_SERVICE_B64" /etc/systemd/system/project-forge-avahi-alias@.service 0644
+
+    systemctl daemon-reload
+    systemctl enable --now avahi-daemon >/dev/null
+    docker compose -f "$PROXY_ROOT/compose.yaml" up -d
+    docker exec "$CADDY_CONTAINER" caddy validate --config /etc/caddy/Caddyfile >/dev/null
+    write_marker
+}
+
+upgrade_platform() {
+    require_write_prereqs
+    if [[ ! -f "$MARKER" ]]; then
+        echo "Platform marker is absent; use install on a fresh host." >&2
+        exit 7
+    fi
+    local marker_schema marker_distribution marker_version
+    marker_schema="$(marker_value SCHEMA_VERSION || true)"
+    marker_distribution="$(marker_value DISTRIBUTION || true)"
+    marker_version="$(marker_value PLATFORM_VERSION || true)"
+    if [[ "$marker_schema" != "$SCHEMA_VERSION" || "$marker_distribution" != "$DISTRIBUTION" ]]; then
+        echo "Existing platform marker is incompatible; refusing in-place upgrade." >&2
+        exit 8
+    fi
+    if [[ "$marker_version" == "$PLATFORM_VERSION" ]]; then
+        echo "Platform is already at version $PLATFORM_VERSION; no upgrade applied."
+        return 0
+    fi
+
+    install -d -m 0755 "$PROXY_ROOT/conf.d" "$PROXY_ROOT/data" "$PROXY_ROOT/config"
+    install -d -m 0750 "$ROUTE_ROOT"
+    if [[ ! -e "$PROXY_ROOT/conf.d/00-platform-empty.caddy" ]]; then
+        printf '# Platform-owned placeholder; application routes are registered separately.\n' > "$PROXY_ROOT/conf.d/00-platform-empty.caddy"
+        chmod 0644 "$PROXY_ROOT/conf.d/00-platform-empty.caddy"
+    fi
+    if ! docker network inspect "$NETWORK_NAME" >/dev/null 2>&1; then
+        docker network create "$NETWORK_NAME" >/dev/null
+    fi
+    local candidate_dir candidate_compose candidate_caddy backup_dir
+    candidate_dir="$(mktemp -d)"
+    backup_dir="$(mktemp -d)"
+    candidate_compose="$candidate_dir/compose.yaml"
+    candidate_caddy="$candidate_dir/Caddyfile"
+    printf '%s' "$COMPOSE_B64" | base64 --decode > "$candidate_compose"
+    printf '%s' "$CADDYFILE_B64" | base64 --decode > "$candidate_caddy"
+    validate_candidate "$candidate_compose" "$candidate_caddy"
+
+    for path in "$PROXY_ROOT/compose.yaml" "$PROXY_ROOT/Caddyfile" /usr/local/lib/project-forge-platform/publish-alias.sh /etc/systemd/system/project-forge-avahi-alias@.service "$MARKER"; do
+        if [[ -f "$path" ]]; then cp -a "$path" "$backup_dir/$(basename "$path")"; fi
+    done
+
+    rollback() {
+        echo "Upgrade failed; restoring previous platform-managed files." >&2
+        [[ -f "$backup_dir/compose.yaml" ]] && cp -f "$backup_dir/compose.yaml" "$PROXY_ROOT/compose.yaml"
+        [[ -f "$backup_dir/Caddyfile" ]] && cp -f "$backup_dir/Caddyfile" "$PROXY_ROOT/Caddyfile"
+        [[ -f "$backup_dir/publish-alias.sh" ]] && cp -f "$backup_dir/publish-alias.sh" /usr/local/lib/project-forge-platform/publish-alias.sh
+        [[ -f "$backup_dir/project-forge-avahi-alias@.service" ]] && cp -f "$backup_dir/project-forge-avahi-alias@.service" /etc/systemd/system/project-forge-avahi-alias@.service
+        [[ -f "$backup_dir/platform.env" ]] && cp -f "$backup_dir/platform.env" "$MARKER"
+        systemctl daemon-reload || true
+        docker compose -f "$PROXY_ROOT/compose.yaml" up -d || true
+        docker exec "$CADDY_CONTAINER" caddy reload --config /etc/caddy/Caddyfile || true
+    }
+
+    set +e
+    decode_to "$COMPOSE_B64" "$PROXY_ROOT/compose.yaml" 0644
+    rc=$?
+    [[ $rc -eq 0 ]] && decode_to "$CADDYFILE_B64" "$PROXY_ROOT/Caddyfile" 0644; rc=$(( rc == 0 ? $? : rc ))
+    [[ $rc -eq 0 ]] && decode_to "$PUBLISH_ALIAS_B64" /usr/local/lib/project-forge-platform/publish-alias.sh 0755; rc=$(( rc == 0 ? $? : rc ))
+    [[ $rc -eq 0 ]] && decode_to "$AVAHI_SERVICE_B64" /etc/systemd/system/project-forge-avahi-alias@.service 0644; rc=$(( rc == 0 ? $? : rc ))
+    [[ $rc -eq 0 ]] && systemctl daemon-reload; rc=$(( rc == 0 ? $? : rc ))
+    [[ $rc -eq 0 ]] && systemctl enable --now avahi-daemon >/dev/null; rc=$(( rc == 0 ? $? : rc ))
+    [[ $rc -eq 0 ]] && docker compose -f "$PROXY_ROOT/compose.yaml" up -d; rc=$(( rc == 0 ? $? : rc ))
+    [[ $rc -eq 0 ]] && docker exec "$CADDY_CONTAINER" caddy reload --config /etc/caddy/Caddyfile; rc=$(( rc == 0 ? $? : rc ))
+    if [[ $rc -eq 0 ]]; then write_marker; rc=$?; fi
+    set -e
+    if [[ $rc -ne 0 ]]; then
+        rollback
+        rm -rf "$candidate_dir" "$backup_dir"
+        exit "$rc"
+    fi
+    rm -rf "$candidate_dir" "$backup_dir"
+}
+
+case "$ACTION" in
+    status)
+        status
+        ;;
+    install|upgrade)
+        exec 9>>"$LOCK_FILE"
+        if ! flock -n 9; then
+            echo "Another host-platform operation holds the lock." >&2
+            exit 75
+        fi
+        if [[ "$ACTION" == install ]]; then install_platform; else upgrade_platform; fi
+        status
+        ;;
+    *)
+        echo "Unsupported platform action: $ACTION" >&2
+        exit 2
+        ;;
+esac
+'''