@mriekki/lean 0.0.0-stage → 0.1.1

package/assets/generated/deployment/src/lean_poc_deployment/app_runtime_remote.py

@@ -0,0 +1,416 @@
+"""Remote Bash template for generic application runtime deployment."""
+
+REMOTE_SCRIPT = r'''#!/usr/bin/env bash
+set -Eeuo pipefail
+
+ACTION="$1"
+EXPECTED_SPEC_SHA="${2:-}"
+DEPLOY_USER="${3:-}"
+APP_ROOT="__APP_ROOT__"
+APP_SCHEMA_VERSION="__APP_SCHEMA_VERSION__"
+NETWORK_NAME="__NETWORK_NAME__"
+CADDY_CONTAINER="__CADDY_CONTAINER__"
+DESIRED_PRESENT="__DESIRED_PRESENT__"
+
+D_OWNER_B64="__D_OWNER_B64__"
+D_ENV_B64="__D_ENV_B64__"
+D_APP_B64="__D_APP_B64__"
+D_CONTAINER_B64="__D_CONTAINER_B64__"
+D_IMAGE_B64="__D_IMAGE_B64__"
+D_PORT="__D_PORT__"
+D_HEALTH_B64="__D_HEALTH_B64__"
+D_RUN_AS_B64="__D_RUN_AS_B64__"
+D_PERSISTENCE="__D_PERSISTENCE__"
+D_DATA_TARGET_B64="__D_DATA_TARGET_B64__"
+D_SPEC_SHA="__D_SPEC_SHA__"
+D_ENV_KEYS=(__D_ENV_KEYS__)
+D_ENV_VALUES=(__D_ENV_VALUES__)
+
+b64d() { printf '%s' "$1" | base64 --decode; }
+meta_value() {
+    local path="$1" key="$2"
+    [[ -f "$path" ]] || return 1
+    sed -n "s/^${key}=//p" "$path" | head -n1
+}
+valid_slug() { [[ "$1" =~ ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ ]]; }
+valid_repo() { [[ "$1" =~ ^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$ ]]; }
+valid_container() { [[ "$1" =~ ^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$ ]]; }
+valid_image() { [[ "$1" =~ ^[A-Za-z0-9][A-Za-z0-9._/:+-]*@sha256:[0-9a-f]{64}$ ]]; }
+valid_port() { [[ "$1" =~ ^[0-9]+$ ]] && (( 1 <= 10#$1 && 10#$1 <= 65535 )); }
+valid_run_as() { [[ "$1" =~ ^[0-9]+(:[0-9]+)?$ ]]; }
+valid_env_key() { [[ "$1" =~ ^[A-Za-z_][A-Za-z0-9_]*$ ]]; }
+
+platform_ready() {
+    [[ -f /srv/lean-poc-platform/platform.env ]] &&
+    docker network inspect "$NETWORK_NAME" >/dev/null 2>&1 &&
+    [[ "$(docker inspect --format '{{.State.Status}}' "$CADDY_CONTAINER" 2>/dev/null || true)" == "running" ]]
+}
+
+network_has_container() {
+    local container="$1"
+    docker network inspect "$NETWORK_NAME" --format '{{range .Containers}}{{.Name}}{{"\n"}}{{end}}' 2>/dev/null |
+        grep -Fxq "$container"
+}
+
+probe_http() {
+    local container="$1" port="$2" path="$3"
+    docker exec "$CADDY_CONTAINER" \
+        wget -q -T 5 -O /dev/null "http://${container}:${port}${path}" >/dev/null 2>&1
+}
+
+wait_ready() {
+    local container="$1" port="$2" path="$3"
+    local deadline=$((SECONDS + 120)) state=""
+    while (( SECONDS < deadline )); do
+        state="$(docker inspect --format '{{.State.Status}}' "$container" 2>/dev/null || true)"
+        if [[ "$state" == "running" ]] && network_has_container "$container" && probe_http "$container" "$port" "$path"; then
+            return 0
+        fi
+        if [[ "$state" == "exited" || "$state" == "dead" ]]; then
+            return 1
+        fi
+        sleep 2
+    done
+    return 1
+}
+
+inventory() {
+    local count=0 state current previous release_file
+    local owner env app container image spec_sha port health persistence
+    local running connected healthy
+    if [[ -d "$APP_ROOT" ]]; then
+        while IFS= read -r state; do
+            [[ -n "$state" ]] || continue
+            owner="$(meta_value "$state" OWNER_REPO || true)"
+            env="$(meta_value "$state" ENVIRONMENT || true)"
+            app="$(meta_value "$state" APP_SLUG || true)"
+            current="$(meta_value "$state" CURRENT_RELEASE || true)"
+            previous="$(meta_value "$state" PREVIOUS_RELEASE || true)"
+            spec_sha="$(meta_value "$state" SPEC_SHA256 || true)"
+            [[ -n "$owner" && -n "$env" && -n "$app" && -n "$current" && -n "$spec_sha" ]] || {
+                echo "Managed application state is malformed: $state" >&2
+                exit 31
+            }
+            release_file="$(dirname "$state")/releases/$current/release.env"
+            [[ -f "$release_file" && ! -L "$release_file" ]] || {
+                echo "Current application release metadata is missing: $release_file" >&2
+                exit 31
+            }
+            container="$(meta_value "$release_file" CONTAINER_NAME || true)"
+            image="$(meta_value "$release_file" IMAGE || true)"
+            port="$(meta_value "$release_file" RUNTIME_PORT || true)"
+            health="$(b64d "$(meta_value "$release_file" HEALTH_PATH_B64 || true)")"
+            persistence="$(meta_value "$release_file" PERSISTENCE_MODE || true)"
+            [[ "$(meta_value "$release_file" SPEC_SHA256 || true)" == "$spec_sha" ]] || {
+                echo "Application state/release fingerprint mismatch: $state" >&2
+                exit 31
+            }
+            running=false
+            connected=false
+            healthy=false
+            [[ "$(docker inspect --format '{{.State.Status}}' "$container" 2>/dev/null || true)" == "running" ]] && running=true || true
+            network_has_container "$container" && connected=true || true
+            if [[ "$running" == true && "$connected" == true ]]; then
+                probe_http "$container" "$port" "$health" && healthy=true || true
+            fi
+            printf 'APP\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\n' \
+                "$owner" "$env" "$app" "$container" "$image" "$spec_sha" "$port" "$health" "$persistence" \
+                "$current" "$previous" "$running" "$connected" "$healthy"
+            count=$((count + 1))
+        done < <(find "$APP_ROOT" -mindepth 3 -maxdepth 3 -type f -name deployment.env -print 2>/dev/null | sort)
+    fi
+    printf 'SUMMARY\tappCount\t%s\n' "$count"
+}
+
+configure_registry_auth() {
+    [[ -n "$DEPLOY_USER" ]] || { echo "Deployment account is required." >&2; exit 32; }
+    [[ "$DEPLOY_USER" =~ ^[A-Za-z_][A-Za-z0-9_.-]{0,31}$ ]] || {
+        echo "Deployment account contains unsupported characters." >&2
+        exit 32
+    }
+    local home config dir_mode file_mode deploy_uid
+    home="$(getent passwd "$DEPLOY_USER" | cut -d: -f6)"
+    [[ -n "$home" && "$home" == /* ]] || { echo "Could not resolve deployment account home." >&2; exit 32; }
+    config="$home/.docker"
+    if [[ ! -e "$config/config.json" ]]; then
+        return 0
+    fi
+    [[ -d "$config" && ! -L "$config" && -f "$config/config.json" && ! -L "$config/config.json" ]] || {
+        echo "Docker credential path is not a regular protected directory/file." >&2
+        exit 32
+    }
+    dir_mode="$(stat -c '%a' "$config")"
+    file_mode="$(stat -c '%a' "$config/config.json")"
+    deploy_uid="$(id -u "$DEPLOY_USER")"
+    if (( (8#$dir_mode & 077) != 0 || (8#$file_mode & 077) != 0 )) ||
+       [[ "$(stat -c '%u' "$config")" != "$deploy_uid" || "$(stat -c '%u' "$config/config.json")" != "$deploy_uid" ]]; then
+        echo "Docker credentials must be owned by the deployment account and deny group/other access." >&2
+        exit 32
+    fi
+    export DOCKER_CONFIG="$config"
+}
+
+decode_desired() {
+    [[ "$DESIRED_PRESENT" == true ]] || { echo "Deploy action omitted desired runtime spec." >&2; exit 33; }
+    D_OWNER="$(b64d "$D_OWNER_B64")"
+    D_ENV="$(b64d "$D_ENV_B64")"
+    D_APP="$(b64d "$D_APP_B64")"
+    D_CONTAINER="$(b64d "$D_CONTAINER_B64")"
+    D_IMAGE="$(b64d "$D_IMAGE_B64")"
+    D_HEALTH="$(b64d "$D_HEALTH_B64")"
+    D_RUN_AS="$(b64d "$D_RUN_AS_B64")"
+    D_DATA_TARGET="$(b64d "$D_DATA_TARGET_B64")"
+
+    valid_repo "$D_OWNER" || { echo "Invalid owner repository." >&2; exit 33; }
+    valid_slug "$D_ENV" || { echo "Invalid environment slug." >&2; exit 33; }
+    valid_slug "$D_APP" || { echo "Invalid application slug." >&2; exit 33; }
+    valid_container "$D_CONTAINER" || { echo "Invalid container name." >&2; exit 33; }
+    valid_image "$D_IMAGE" || { echo "Image is not an immutable sha256 digest reference." >&2; exit 33; }
+    valid_port "$D_PORT" || { echo "Invalid runtime port." >&2; exit 33; }
+    [[ "$D_HEALTH" == /* && "$D_HEALTH" != *$'\n'* && "$D_HEALTH" != *$'\r'* ]] || {
+        echo "Invalid health path." >&2
+        exit 33
+    }
+    valid_run_as "$D_RUN_AS" || { echo "Invalid numeric runAs value." >&2; exit 33; }
+    [[ "$D_PERSISTENCE" == "none" || "$D_PERSISTENCE" == "directory" ]] || {
+        echo "Invalid persistence mode." >&2
+        exit 33
+    }
+    if [[ "$D_PERSISTENCE" == "directory" ]]; then
+        [[ "$D_DATA_TARGET" == /* && "$D_DATA_TARGET" != *"/../"* && "$D_DATA_TARGET" != *$'\n'* ]] || {
+            echo "Invalid persistent data container path." >&2
+            exit 33
+        }
+    elif [[ -n "$D_DATA_TARGET" ]]; then
+        echo "Non-persistent runtime unexpectedly supplied a data path." >&2
+        exit 33
+    fi
+    [[ "$D_SPEC_SHA" =~ ^[0-9a-f]{64}$ ]] || { echo "Invalid runtime spec fingerprint." >&2; exit 33; }
+    [[ "${#D_ENV_KEYS[@]}" -eq "${#D_ENV_VALUES[@]}" ]] || { echo "Environment payload mismatch." >&2; exit 33; }
+
+    local index key
+    for index in "${!D_ENV_KEYS[@]}"; do
+        key="$(b64d "${D_ENV_KEYS[$index]}")"
+        valid_env_key "$key" || { echo "Invalid environment variable name." >&2; exit 33; }
+    done
+}
+
+release_value() {
+    meta_value "$1" "$2"
+}
+
+write_release_metadata() {
+    local release_file="$1"
+    local tmp="$release_file.tmp.$$" index key_b64 value_b64
+    {
+        printf 'SCHEMA_VERSION=%s\n' "$APP_SCHEMA_VERSION"
+        printf 'OWNER_REPO=%s\n' "$D_OWNER"
+        printf 'ENVIRONMENT=%s\n' "$D_ENV"
+        printf 'APP_SLUG=%s\n' "$D_APP"
+        printf 'CONTAINER_NAME=%s\n' "$D_CONTAINER"
+        printf 'IMAGE=%s\n' "$D_IMAGE"
+        printf 'RUNTIME_PORT=%s\n' "$D_PORT"
+        printf 'HEALTH_PATH_B64=%s\n' "$D_HEALTH_B64"
+        printf 'RUN_AS=%s\n' "$D_RUN_AS"
+        printf 'PERSISTENCE_MODE=%s\n' "$D_PERSISTENCE"
+        printf 'DATA_TARGET_B64=%s\n' "$D_DATA_TARGET_B64"
+        printf 'SPEC_SHA256=%s\n' "$D_SPEC_SHA"
+        printf 'ENV_COUNT=%s\n' "${#D_ENV_KEYS[@]}"
+        for index in "${!D_ENV_KEYS[@]}"; do
+            key_b64="${D_ENV_KEYS[$index]}"
+            value_b64="${D_ENV_VALUES[$index]}"
+            printf 'ENV_KEY_B64_%s=%s\n' "$index" "$key_b64"
+            printf 'ENV_VALUE_B64_%s=%s\n' "$index" "$value_b64"
+        done
+    } > "$tmp"
+    chmod 0600 "$tmp"
+    mv -f "$tmp" "$release_file"
+}
+
+start_desired_container() {
+    local root data
+    local uid gid index key value
+    root="$1"
+    data="$root/data"
+    uid="${D_RUN_AS%%:*}"
+    if [[ "$D_RUN_AS" == *:* ]]; then gid="${D_RUN_AS#*:}"; else gid="$uid"; fi
+
+    if [[ "$D_PERSISTENCE" == "directory" ]]; then
+        if [[ -L "$data" ]]; then
+            echo "Persistent data directory must not be a symbolic link." >&2
+            return 1
+        fi
+        if [[ ! -e "$data" ]]; then
+            install -d -m 0750 -o "$uid" -g "$gid" "$data"
+        elif [[ ! -d "$data" ]]; then
+            echo "Persistent data path is not a directory." >&2
+            return 1
+        elif [[ "$(stat -c '%u' "$data")" != "$uid" || "$(stat -c '%g' "$data")" != "$gid" ]]; then
+            echo "Persistent data directory ownership does not match runAs; use the persistence adapter/import path." >&2
+            return 1
+        fi
+    fi
+
+    local -a docker_args
+    docker_args=(
+        docker run -d
+        --name "$D_CONTAINER"
+        --restart unless-stopped
+        --network "$NETWORK_NAME"
+        --user "$D_RUN_AS"
+        --log-driver json-file
+        --log-opt max-size=10m
+        --log-opt max-file=3
+    )
+    if [[ "$D_PERSISTENCE" == "directory" ]]; then
+        docker_args+=(--mount "type=bind,src=$data,dst=$D_DATA_TARGET")
+    fi
+    for index in "${!D_ENV_KEYS[@]}"; do
+        key="$(b64d "${D_ENV_KEYS[$index]}")"
+        value="$(b64d "${D_ENV_VALUES[$index]}")"
+        docker_args+=(--env "$key=$value")
+    done
+    docker_args+=("$D_IMAGE")
+    "${docker_args[@]}" >/dev/null
+}
+
+record_evidence() {
+    local root="$1" outcome="$2" release_id="$3" previous="$4"
+    local timestamp
+    timestamp="$(date -u +'%Y-%m-%dT%H:%M:%SZ')"
+    printf '{"timestamp":"%s","ownerRepo":"%s","environment":"%s","appSlug":"%s","container":"%s","image":"%s","specSha256":"%s","release":"%s","previousRelease":"%s","persistence":"%s","outcome":"%s"}\n' \
+        "$timestamp" "$D_OWNER" "$D_ENV" "$D_APP" "$D_CONTAINER" "$D_IMAGE" "$D_SPEC_SHA" \
+        "$release_id" "$previous" "$D_PERSISTENCE" "$outcome" >> "$root/deployment-evidence.jsonl"
+    chmod 0600 "$root/deployment-evidence.jsonl"
+}
+
+deploy() {
+    platform_ready || { echo "Kit shared platform is not ready." >&2; exit 34; }
+    decode_desired
+    configure_registry_auth
+
+    local root releases state current_release="" previous_release="" current_spec="" current_container="" next_previous=""
+    local digest release_id release_dir release_file lock_file tmp
+    root="$APP_ROOT/$D_APP/$D_ENV"
+    releases="$root/releases"
+    state="$root/deployment.env"
+    lock_file="/run/lock/lean-poc-app-$D_APP--$D_ENV.lock"
+    digest="${D_IMAGE##*@sha256:}"
+    release_id="sha256-${digest}-${D_SPEC_SHA:0:16}"
+    release_dir="$releases/$release_id"
+    release_file="$release_dir/release.env"
+
+    exec 9>>"$lock_file"
+    if ! flock -n 9; then
+        echo "Another application deployment holds the lock for $D_APP--$D_ENV." >&2
+        exit 75
+    fi
+
+    for path in "$root" "$releases" "$state" "$root/data" "$root/deployment-evidence.jsonl"; do
+        [[ ! -L "$path" ]] || { echo "Managed application path must not be a symbolic link: $path" >&2; exit 35; }
+    done
+
+    if [[ -f "$state" ]]; then
+        [[ "$(meta_value "$state" OWNER_REPO || true)" == "$D_OWNER" &&
+           "$(meta_value "$state" ENVIRONMENT || true)" == "$D_ENV" &&
+           "$(meta_value "$state" APP_SLUG || true)" == "$D_APP" ]] || {
+            echo "Existing application state has different ownership." >&2
+            exit 35
+        }
+        current_release="$(meta_value "$state" CURRENT_RELEASE || true)"
+        previous_release="$(meta_value "$state" PREVIOUS_RELEASE || true)"
+        current_spec="$(meta_value "$state" SPEC_SHA256 || true)"
+        [[ -n "$current_release" && "$current_spec" =~ ^[0-9a-f]{64}$ ]] || {
+            echo "Existing application state is malformed." >&2
+            exit 35
+        }
+        [[ "$EXPECTED_SPEC_SHA" != "NONE" && "$current_spec" == "$EXPECTED_SPEC_SHA" ]] || {
+            echo "Application state changed after planning; create a fresh plan." >&2
+            exit 36
+        }
+        local current_file="$releases/$current_release/release.env"
+        [[ -f "$current_file" && ! -L "$current_file" ]] || {
+            echo "Current release metadata is missing." >&2
+            exit 35
+        }
+        current_container="$(release_value "$current_file" CONTAINER_NAME || true)"
+        valid_container "$current_container" || { echo "Current release container metadata is malformed." >&2; exit 35; }
+        if [[ "$current_spec" == "$D_SPEC_SHA" ]]; then
+            next_previous="$previous_release"
+        else
+            next_previous="$current_release"
+        fi
+    else
+        [[ "$EXPECTED_SPEC_SHA" == "NONE" ]] || {
+            echo "Application state disappeared after planning; create a fresh plan." >&2
+            exit 36
+        }
+    fi
+
+    if docker inspect "$D_CONTAINER" >/dev/null 2>&1 && [[ "$D_CONTAINER" != "$current_container" ]]; then
+        echo "Desired container name is already occupied outside this managed runtime." >&2
+        exit 37
+    fi
+
+    install -d -m 0750 "$APP_ROOT" "$APP_ROOT/$D_APP" "$root" "$releases"
+    if [[ -e "$release_dir" && ! -d "$release_dir" ]]; then
+        echo "Release path exists and is not a directory." >&2
+        exit 35
+    fi
+    install -d -m 0750 "$release_dir"
+    if [[ -f "$release_file" ]]; then
+        [[ "$(release_value "$release_file" SPEC_SHA256 || true)" == "$D_SPEC_SHA" ]] || {
+            echo "Release directory collision with different runtime metadata." >&2
+            exit 35
+        }
+    else
+        write_release_metadata "$release_file"
+    fi
+
+    docker pull "$D_IMAGE" >/dev/null
+
+    if [[ -n "$current_container" ]]; then
+        docker rm -f "$current_container" >/dev/null
+    fi
+
+    if ! start_desired_container "$root"; then
+        docker rm -f "$D_CONTAINER" >/dev/null 2>&1 || true
+        record_evidence "$root" "failed-start" "$release_id" "$current_release"
+        echo "Application container failed to start; previous release metadata was retained but runtime rollback was not attempted." >&2
+        exit 38
+    fi
+    if ! wait_ready "$D_CONTAINER" "$D_PORT" "$D_HEALTH"; then
+        docker rm -f "$D_CONTAINER" >/dev/null 2>&1 || true
+        record_evidence "$root" "failed-readiness" "$release_id" "$current_release"
+        echo "Application failed readiness; previous release metadata was retained but runtime rollback was not attempted." >&2
+        exit 39
+    fi
+
+    tmp="$state.tmp.$$"
+    {
+        printf 'SCHEMA_VERSION=%s\n' "$APP_SCHEMA_VERSION"
+        printf 'OWNER_REPO=%s\n' "$D_OWNER"
+        printf 'ENVIRONMENT=%s\n' "$D_ENV"
+        printf 'APP_SLUG=%s\n' "$D_APP"
+        printf 'CURRENT_RELEASE=%s\n' "$release_id"
+        printf 'PREVIOUS_RELEASE=%s\n' "$next_previous"
+        printf 'SPEC_SHA256=%s\n' "$D_SPEC_SHA"
+    } > "$tmp"
+    chmod 0600 "$tmp"
+    mv -f "$tmp" "$state"
+    record_evidence "$root" "deployed" "$release_id" "$next_previous"
+}
+
+case "$ACTION" in
+    inventory)
+        inventory
+        ;;
+    deploy)
+        deploy
+        ;;
+    *)
+        echo "Unsupported application-runtime action: $ACTION" >&2
+        exit 2
+        ;;
+esac
+'''

package/assets/generated/deployment/src/lean_poc_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