@mriekki/lean 0.1.0 → 0.2.0

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

@@ -1,455 +1,455 @@
-"""Generic immutable application-runtime deployment for Kit-managed hosts."""
-
-from __future__ import annotations
-
-import base64
-import hashlib
-import json
-import re
-import subprocess
-from typing import Any, Iterable
-
-from .box_platform import platform_status
-from .box_platform_assets import CADDY_CONTAINER, NETWORK_NAME
-from .errors import DeploymentKitError
-from .profiles import load_profile
-from .ssh import ssh_args, verify_access
-from .app_runtime_remote import REMOTE_SCRIPT
-
-APP_ROOT = "/srv/lean-poc-apps"
-APP_SCHEMA_VERSION = 1
-APP_DEPLOY_WRITE_PHRASE = "[APP DEPLOY WRITE]"
-PRODUCTION_APP_DEPLOY_WRITE_PHRASE = "[PRODUCTION APP DEPLOY]"
-
-_SLUG_RE = re.compile(r"^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$")
-_REPO_RE = re.compile(r"^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$")
-_CONTAINER_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$")
-_IMAGE_RE = re.compile(
-    r"^[A-Za-z0-9][A-Za-z0-9._/:+-]*@sha256:[0-9a-f]{64}$"
-)
-_RUN_AS_RE = re.compile(r"^[0-9]+(?::[0-9]+)?$")
-_ENV_KEY_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
-_HEALTH_PATH_RE = re.compile(r"^/[A-Za-z0-9._~!$&'()*+,;=:@%/\-]*$")
-_CONTAINER_PATH_RE = re.compile(r"^/[A-Za-z0-9._~+:/\-]*$")
-
-
-def _slug(value: str, field: str) -> str:
-    if not isinstance(value, str) or _SLUG_RE.fullmatch(value) is None:
-        raise DeploymentKitError(f"{field} must use lowercase letters, digits, and internal hyphens.")
-    return value
-
-
-def _owner_repo(value: str) -> str:
-    if not isinstance(value, str) or _REPO_RE.fullmatch(value) is None:
-        raise DeploymentKitError("ownerRepo must use GitHub owner/repository form without URL syntax.")
-    return value
-
-
-def _container_name(value: str) -> str:
-    if not isinstance(value, str) or _CONTAINER_RE.fullmatch(value) is None:
-        raise DeploymentKitError("containerName contains unsupported characters.")
-    return value
-
-
-def _image(value: str) -> str:
-    if not isinstance(value, str) or _IMAGE_RE.fullmatch(value) is None:
-        raise DeploymentKitError("image must be an immutable image reference ending in @sha256:<64 lowercase hex>.")
-    return value
-
-
-def _runtime_port(value: int) -> int:
-    if type(value) is not int or not 1 <= value <= 65535:
-        raise DeploymentKitError("runtimePort must be an integer from 1 through 65535.")
-    return value
-
-
-def _health_path(value: str) -> str:
-    if not isinstance(value, str) or _HEALTH_PATH_RE.fullmatch(value) is None:
-        raise DeploymentKitError("healthPath must be a safe absolute HTTP path.")
-    return value
-
-
-def _run_as(value: str) -> str:
-    if not isinstance(value, str) or _RUN_AS_RE.fullmatch(value) is None:
-        raise DeploymentKitError("runAs must be a numeric UID or UID:GID.")
-    return value
-
-
-def _container_path(value: str | None) -> str | None:
-    if value is None:
-        return None
-    if not isinstance(value, str) or _CONTAINER_PATH_RE.fullmatch(value) is None or "/../" in f"{value}/":
-        raise DeploymentKitError("dataContainerPath must be a safe absolute container path.")
-    return value.rstrip("/") or "/"
-
-
-def _normalize_environment_variables(items: dict[str, str] | Iterable[tuple[str, str]]) -> dict[str, str]:
-    pairs = items.items() if isinstance(items, dict) else items
-    result: dict[str, str] = {}
-    for key, value in pairs:
-        if not isinstance(key, str) or _ENV_KEY_RE.fullmatch(key) is None:
-            raise DeploymentKitError(f"Invalid environment variable name: {key!r}")
-        if key in result:
-            raise DeploymentKitError(f"Duplicate environment variable: {key}")
-        if not isinstance(value, str) or "\x00" in value or "\n" in value or "\r" in value:
-            raise DeploymentKitError(f"Environment variable {key} contains unsupported control characters.")
-        result[key] = value
-    return dict(sorted(result.items()))
-
-
-def normalize_app_spec(
-    *,
-    owner_repo: str,
-    environment: str,
-    app_slug: str,
-    container_name: str,
-    image: str,
-    runtime_port: int,
-    health_path: str,
-    run_as: str,
-    persistence_mode: str,
-    data_container_path: str | None,
-    environment_variables: dict[str, str] | Iterable[tuple[str, str]],
-) -> dict[str, Any]:
-    if persistence_mode not in {"none", "directory"}:
-        raise DeploymentKitError("persistenceMode must be 'none' or 'directory'.")
-    data_path = _container_path(data_container_path)
-    if persistence_mode == "directory" and data_path is None:
-        raise DeploymentKitError("directory persistence requires dataContainerPath.")
-    if persistence_mode == "none" and data_path is not None:
-        raise DeploymentKitError("dataContainerPath must be omitted when persistenceMode is 'none'.")
-    spec = {
-        "schemaVersion": APP_SCHEMA_VERSION,
-        "ownerRepo": _owner_repo(owner_repo),
-        "environment": _slug(environment, "environment"),
-        "appSlug": _slug(app_slug, "appSlug"),
-        "containerName": _container_name(container_name),
-        "image": _image(image),
-        "runtimePort": _runtime_port(runtime_port),
-        "healthPath": _health_path(health_path),
-        "runAs": _run_as(run_as),
-        "persistence": {
-            "mode": persistence_mode,
-            "dataContainerPath": data_path,
-        },
-        "environmentVariables": _normalize_environment_variables(environment_variables),
-    }
-    spec["specSha256"] = _spec_sha(spec)
-    return spec
-
-
-def _spec_sha(spec: dict[str, Any]) -> str:
-    value = {key: spec[key] for key in spec if key != "specSha256"}
-    return hashlib.sha256(
-        json.dumps(value, sort_keys=True, separators=(",", ":")).encode("utf-8")
-    ).hexdigest()
-
-
-def _b64(value: str) -> str:
-    return base64.b64encode(value.encode("utf-8")).decode("ascii")
-
-
-def build_remote_script(spec: dict[str, Any] | None = None) -> str:
-    env_keys: list[str] = []
-    env_values: list[str] = []
-    desired = {
-        "ownerRepo": "",
-        "environment": "",
-        "appSlug": "",
-        "containerName": "",
-        "image": "",
-        "runtimePort": "",
-        "healthPath": "",
-        "runAs": "",
-        "persistenceMode": "",
-        "dataContainerPath": "",
-        "specSha256": "",
-    }
-    if spec is not None:
-        desired.update(
-            ownerRepo=spec["ownerRepo"],
-            environment=spec["environment"],
-            appSlug=spec["appSlug"],
-            containerName=spec["containerName"],
-            image=spec["image"],
-            runtimePort=str(spec["runtimePort"]),
-            healthPath=spec["healthPath"],
-            runAs=spec["runAs"],
-            persistenceMode=spec["persistence"]["mode"],
-            dataContainerPath=spec["persistence"]["dataContainerPath"] or "",
-            specSha256=spec["specSha256"],
-        )
-        for key, value in spec["environmentVariables"].items():
-            env_keys.append(_b64(key))
-            env_values.append(_b64(value))
-
-    replacements = {
-        "__APP_ROOT__": APP_ROOT,
-        "__APP_SCHEMA_VERSION__": str(APP_SCHEMA_VERSION),
-        "__NETWORK_NAME__": NETWORK_NAME,
-        "__CADDY_CONTAINER__": CADDY_CONTAINER,
-        "__DESIRED_PRESENT__": "true" if spec is not None else "false",
-        "__D_OWNER_B64__": _b64(desired["ownerRepo"]),
-        "__D_ENV_B64__": _b64(desired["environment"]),
-        "__D_APP_B64__": _b64(desired["appSlug"]),
-        "__D_CONTAINER_B64__": _b64(desired["containerName"]),
-        "__D_IMAGE_B64__": _b64(desired["image"]),
-        "__D_PORT__": desired["runtimePort"],
-        "__D_HEALTH_B64__": _b64(desired["healthPath"]),
-        "__D_RUN_AS_B64__": _b64(desired["runAs"]),
-        "__D_PERSISTENCE__": desired["persistenceMode"],
-        "__D_DATA_TARGET_B64__": _b64(desired["dataContainerPath"]),
-        "__D_SPEC_SHA__": desired["specSha256"],
-        "__D_ENV_KEYS__": " ".join(f"'{item}'" for item in env_keys),
-        "__D_ENV_VALUES__": " ".join(f"'{item}'" for item in env_values),
-    }
-    script = REMOTE_SCRIPT
-    for placeholder, value in replacements.items():
-        script = script.replace(placeholder, value)
-    if "__" in script:
-        raise DeploymentKitError("Internal application-runtime script contains an unresolved placeholder.")
-    return script
-
-
-def _parse_inventory(output: str) -> dict[str, Any]:
-    apps: list[dict[str, Any]] = []
-    summary: dict[str, str] = {}
-    for raw in output.splitlines():
-        if not raw:
-            continue
-        parts = raw.split("\t")
-        if parts[0] == "SUMMARY":
-            if len(parts) != 3 or parts[1] in summary:
-                raise DeploymentKitError("Malformed or duplicate application inventory summary.")
-            summary[parts[1]] = parts[2]
-            continue
-        if parts[0] != "APP" or len(parts) != 15:
-            raise DeploymentKitError("Malformed application inventory record.")
-        try:
-            port = int(parts[7])
-        except ValueError as error:
-            raise DeploymentKitError("Malformed application inventory runtime port.") from error
-        if parts[12] not in {"true", "false"} or parts[13] not in {"true", "false"}:
-            raise DeploymentKitError("Malformed application inventory boolean value.")
-        owner = _owner_repo(parts[1])
-        environment = _slug(parts[2], "environment")
-        app_slug = _slug(parts[3], "appSlug")
-        container = _container_name(parts[4])
-        image = _image(parts[5])
-        if re.fullmatch(r"[0-9a-f]{64}", parts[6]) is None:
-            raise DeploymentKitError("Malformed application inventory spec fingerprint.")
-        health_path = _health_path(parts[8])
-        if parts[9] not in {"none", "directory"}:
-            raise DeploymentKitError("Malformed application inventory persistence mode.")
-        app = {
-            "ownerRepo": owner,
-            "environment": environment,
-            "appSlug": app_slug,
-            "containerName": container,
-            "image": image,
-            "specSha256": parts[6],
-            "runtimePort": port,
-            "healthPath": health_path,
-            "persistenceMode": parts[9],
-            "currentRelease": parts[10] or None,
-            "previousRelease": parts[11] or None,
-            "containerRunning": parts[12] == "true",
-            "connectedToSharedNetwork": parts[13] == "true",
-            "httpHealthy": parts[14] == "true",
-        }
-        apps.append(app)
-    if set(summary) != {"appCount"}:
-        raise DeploymentKitError("Application inventory omitted appCount.")
-    try:
-        count = int(summary["appCount"])
-    except ValueError as error:
-        raise DeploymentKitError("Malformed application inventory count.") from error
-    if count != len(apps):
-        raise DeploymentKitError("Application inventory count does not match records.")
-    keys = [(item["appSlug"], item["environment"]) for item in apps]
-    if len(keys) != len(set(keys)):
-        raise DeploymentKitError("Duplicate application/environment ownership records were reported.")
-    return {"applications": sorted(apps, key=lambda item: (item["appSlug"], item["environment"]))}
-
-
-def _run_remote(
-    profile: dict[str, Any],
-    address: str,
-    action: str,
-    *,
-    spec: dict[str, Any] | None = None,
-    expected_spec_sha: str = "",
-) -> str:
-    if action not in {"inventory", "deploy"}:
-        raise DeploymentKitError(f"Unsupported application-runtime action: {action}")
-    args = [action]
-    if action == "deploy":
-        args.extend([expected_spec_sha or "NONE", profile["user"]])
-    command = ssh_args(
-        profile,
-        address,
-        command="sudo -n bash -s -- " + " ".join(args),
-    )
-    completed = subprocess.run(
-        command,
-        input=build_remote_script(spec).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 application-runtime {action} failed: {detail}")
-    return stdout
-
-
-def app_inventory(name: str) -> dict[str, Any]:
-    profile = load_profile(name)
-    evidence = verify_access(profile)
-    inventory = _parse_inventory(
-        _run_remote(profile, evidence["address"], "inventory")
-    )
-    inventory["targetName"] = name
-    inventory["verifiedAddress"] = evidence["address"]
-    inventory["mutated"] = False
-    return inventory
-
-
-def _inventory_snapshot(inventory: dict[str, Any]) -> str:
-    value = {"applications": inventory["applications"]}
-    return hashlib.sha256(
-        json.dumps(value, sort_keys=True, separators=(",", ":")).encode("utf-8")
-    ).hexdigest()
-
-
-def _find_app(inventory: dict[str, Any], app_slug: str, environment: str) -> dict[str, Any] | None:
-    return next(
-        (
-            item
-            for item in inventory["applications"]
-            if item["appSlug"] == app_slug and item["environment"] == environment
-        ),
-        None,
-    )
-
-
-def plan_app_deploy(name: str, spec: dict[str, Any]) -> dict[str, Any]:
-    platform = platform_status(name)
-    if platform["state"] != "ready":
-        raise DeploymentKitError(
-            f"Application deployment requires a ready shared platform; target '{name}' is '{platform['state']}'."
-        )
-    inventory = app_inventory(name)
-    existing = _find_app(inventory, spec["appSlug"], spec["environment"])
-    if existing is not None and existing["ownerRepo"] != spec["ownerRepo"]:
-        raise DeploymentKitError("Application/environment ownership does not match the requested repository.")
-    for item in inventory["applications"]:
-        if (
-            item["containerName"] == spec["containerName"]
-            and (item["appSlug"], item["environment"])
-            != (spec["appSlug"], spec["environment"])
-        ):
-            raise DeploymentKitError(
-                f"Container name collision with managed app {item['appSlug']}--{item['environment']}."
-            )
-    if (
-        existing is not None
-        and existing["specSha256"] == spec["specSha256"]
-        and existing["containerRunning"]
-        and existing["connectedToSharedNetwork"]
-        and existing["httpHealthy"]
-    ):
-        raise DeploymentKitError("The exact application runtime spec is already deployed and healthy.")
-    return {
-        "targetName": name,
-        "action": "deploy",
-        "environment": spec["environment"],
-        "appSlug": spec["appSlug"],
-        "ownerRepo": spec["ownerRepo"],
-        "containerName": spec["containerName"],
-        "image": spec["image"],
-        "runtimePort": spec["runtimePort"],
-        "healthPath": spec["healthPath"],
-        "persistenceMode": spec["persistence"]["mode"],
-        "changeType": "update" if existing is not None else "create",
-        "previousImage": existing["image"] if existing is not None else None,
-        "previousRelease": existing["currentRelease"] if existing is not None else None,
-        "retainsPreviousRelease": existing is not None,
-        "publishesHostPort": False,
-        "attachesSharedNetwork": NETWORK_NAME,
-        "modifiesRoutes": False,
-        "persistentDataDeletion": False,
-        "inventorySnapshot": _inventory_snapshot(inventory),
-        "expectedSpecSha256": existing["specSha256"] if existing is not None else None,
-        "spec": spec,
-    }
-
-
-def deploy_write_phrase(plan: dict[str, Any]) -> str:
-    return (
-        PRODUCTION_APP_DEPLOY_WRITE_PHRASE
-        if plan["environment"] == "production"
-        else APP_DEPLOY_WRITE_PHRASE
-    )
-
-
-def apply_app_deploy(plan: dict[str, Any]) -> dict[str, Any]:
-    required = {
-        "targetName",
-        "action",
-        "environment",
-        "appSlug",
-        "ownerRepo",
-        "containerName",
-        "image",
-        "runtimePort",
-        "healthPath",
-        "persistenceMode",
-        "changeType",
-        "previousImage",
-        "previousRelease",
-        "retainsPreviousRelease",
-        "publishesHostPort",
-        "attachesSharedNetwork",
-        "modifiesRoutes",
-        "persistentDataDeletion",
-        "inventorySnapshot",
-        "expectedSpecSha256",
-        "spec",
-    }
-    if not isinstance(plan, dict) or set(plan) != required or plan["action"] != "deploy":
-        raise DeploymentKitError("Malformed application deployment plan.")
-
-    current = app_inventory(plan["targetName"])
-    if _inventory_snapshot(current) != plan["inventorySnapshot"]:
-        raise DeploymentKitError(
-            "Application inventory changed after the plan was reviewed; create and authorize a fresh plan."
-        )
-    platform = platform_status(plan["targetName"])
-    if platform["state"] != "ready":
-        raise DeploymentKitError("Shared host platform is no longer ready; application deployment is blocked.")
-
-    profile = load_profile(plan["targetName"])
-    evidence = verify_access(profile)
-    _run_remote(
-        profile,
-        evidence["address"],
-        "deploy",
-        spec=plan["spec"],
-        expected_spec_sha=plan["expectedSpecSha256"] or "",
-    )
-    final = app_inventory(plan["targetName"])
-    deployed = _find_app(final, plan["appSlug"], plan["environment"])
-    if deployed is None:
-        raise DeploymentKitError("Application deployment returned without managed runtime state.")
-    if deployed["specSha256"] != plan["spec"]["specSha256"]:
-        raise DeploymentKitError("Application deployment returned with a different runtime spec.")
-    if not (
-        deployed["containerRunning"]
-        and deployed["connectedToSharedNetwork"]
-        and deployed["httpHealthy"]
-    ):
-        raise DeploymentKitError("Application deployment completed but runtime readiness is not healthy.")
-    final["mutated"] = True
-    return final
+"""Generic immutable application-runtime deployment for Kit-managed hosts."""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import re
+import subprocess
+from typing import Any, Iterable
+
+from .box_platform import platform_status
+from .box_platform_assets import CADDY_CONTAINER, NETWORK_NAME
+from .errors import DeploymentKitError
+from .profiles import load_profile
+from .ssh import ssh_args, verify_access
+from .app_runtime_remote import REMOTE_SCRIPT
+
+APP_ROOT = "/srv/lean-poc-apps"
+APP_SCHEMA_VERSION = 1
+APP_DEPLOY_WRITE_PHRASE = "[APP DEPLOY WRITE]"
+PRODUCTION_APP_DEPLOY_WRITE_PHRASE = "[PRODUCTION APP DEPLOY]"
+
+_SLUG_RE = re.compile(r"^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$")
+_REPO_RE = re.compile(r"^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$")
+_CONTAINER_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$")
+_IMAGE_RE = re.compile(
+    r"^[A-Za-z0-9][A-Za-z0-9._/:+-]*@sha256:[0-9a-f]{64}$"
+)
+_RUN_AS_RE = re.compile(r"^[0-9]+(?::[0-9]+)?$")
+_ENV_KEY_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+_HEALTH_PATH_RE = re.compile(r"^/[A-Za-z0-9._~!$&'()*+,;=:@%/\-]*$")
+_CONTAINER_PATH_RE = re.compile(r"^/[A-Za-z0-9._~+:/\-]*$")
+
+
+def _slug(value: str, field: str) -> str:
+    if not isinstance(value, str) or _SLUG_RE.fullmatch(value) is None:
+        raise DeploymentKitError(f"{field} must use lowercase letters, digits, and internal hyphens.")
+    return value
+
+
+def _owner_repo(value: str) -> str:
+    if not isinstance(value, str) or _REPO_RE.fullmatch(value) is None:
+        raise DeploymentKitError("ownerRepo must use GitHub owner/repository form without URL syntax.")
+    return value
+
+
+def _container_name(value: str) -> str:
+    if not isinstance(value, str) or _CONTAINER_RE.fullmatch(value) is None:
+        raise DeploymentKitError("containerName contains unsupported characters.")
+    return value
+
+
+def _image(value: str) -> str:
+    if not isinstance(value, str) or _IMAGE_RE.fullmatch(value) is None:
+        raise DeploymentKitError("image must be an immutable image reference ending in @sha256:<64 lowercase hex>.")
+    return value
+
+
+def _runtime_port(value: int) -> int:
+    if type(value) is not int or not 1 <= value <= 65535:
+        raise DeploymentKitError("runtimePort must be an integer from 1 through 65535.")
+    return value
+
+
+def _health_path(value: str) -> str:
+    if not isinstance(value, str) or _HEALTH_PATH_RE.fullmatch(value) is None:
+        raise DeploymentKitError("healthPath must be a safe absolute HTTP path.")
+    return value
+
+
+def _run_as(value: str) -> str:
+    if not isinstance(value, str) or _RUN_AS_RE.fullmatch(value) is None:
+        raise DeploymentKitError("runAs must be a numeric UID or UID:GID.")
+    return value
+
+
+def _container_path(value: str | None) -> str | None:
+    if value is None:
+        return None
+    if not isinstance(value, str) or _CONTAINER_PATH_RE.fullmatch(value) is None or "/../" in f"{value}/":
+        raise DeploymentKitError("dataContainerPath must be a safe absolute container path.")
+    return value.rstrip("/") or "/"
+
+
+def _normalize_environment_variables(items: dict[str, str] | Iterable[tuple[str, str]]) -> dict[str, str]:
+    pairs = items.items() if isinstance(items, dict) else items
+    result: dict[str, str] = {}
+    for key, value in pairs:
+        if not isinstance(key, str) or _ENV_KEY_RE.fullmatch(key) is None:
+            raise DeploymentKitError(f"Invalid environment variable name: {key!r}")
+        if key in result:
+            raise DeploymentKitError(f"Duplicate environment variable: {key}")
+        if not isinstance(value, str) or "\x00" in value or "\n" in value or "\r" in value:
+            raise DeploymentKitError(f"Environment variable {key} contains unsupported control characters.")
+        result[key] = value
+    return dict(sorted(result.items()))
+
+
+def normalize_app_spec(
+    *,
+    owner_repo: str,
+    environment: str,
+    app_slug: str,
+    container_name: str,
+    image: str,
+    runtime_port: int,
+    health_path: str,
+    run_as: str,
+    persistence_mode: str,
+    data_container_path: str | None,
+    environment_variables: dict[str, str] | Iterable[tuple[str, str]],
+) -> dict[str, Any]:
+    if persistence_mode not in {"none", "directory"}:
+        raise DeploymentKitError("persistenceMode must be 'none' or 'directory'.")
+    data_path = _container_path(data_container_path)
+    if persistence_mode == "directory" and data_path is None:
+        raise DeploymentKitError("directory persistence requires dataContainerPath.")
+    if persistence_mode == "none" and data_path is not None:
+        raise DeploymentKitError("dataContainerPath must be omitted when persistenceMode is 'none'.")
+    spec = {
+        "schemaVersion": APP_SCHEMA_VERSION,
+        "ownerRepo": _owner_repo(owner_repo),
+        "environment": _slug(environment, "environment"),
+        "appSlug": _slug(app_slug, "appSlug"),
+        "containerName": _container_name(container_name),
+        "image": _image(image),
+        "runtimePort": _runtime_port(runtime_port),
+        "healthPath": _health_path(health_path),
+        "runAs": _run_as(run_as),
+        "persistence": {
+            "mode": persistence_mode,
+            "dataContainerPath": data_path,
+        },
+        "environmentVariables": _normalize_environment_variables(environment_variables),
+    }
+    spec["specSha256"] = _spec_sha(spec)
+    return spec
+
+
+def _spec_sha(spec: dict[str, Any]) -> str:
+    value = {key: spec[key] for key in spec if key != "specSha256"}
+    return hashlib.sha256(
+        json.dumps(value, sort_keys=True, separators=(",", ":")).encode("utf-8")
+    ).hexdigest()
+
+
+def _b64(value: str) -> str:
+    return base64.b64encode(value.encode("utf-8")).decode("ascii")
+
+
+def build_remote_script(spec: dict[str, Any] | None = None) -> str:
+    env_keys: list[str] = []
+    env_values: list[str] = []
+    desired = {
+        "ownerRepo": "",
+        "environment": "",
+        "appSlug": "",
+        "containerName": "",
+        "image": "",
+        "runtimePort": "",
+        "healthPath": "",
+        "runAs": "",
+        "persistenceMode": "",
+        "dataContainerPath": "",
+        "specSha256": "",
+    }
+    if spec is not None:
+        desired.update(
+            ownerRepo=spec["ownerRepo"],
+            environment=spec["environment"],
+            appSlug=spec["appSlug"],
+            containerName=spec["containerName"],
+            image=spec["image"],
+            runtimePort=str(spec["runtimePort"]),
+            healthPath=spec["healthPath"],
+            runAs=spec["runAs"],
+            persistenceMode=spec["persistence"]["mode"],
+            dataContainerPath=spec["persistence"]["dataContainerPath"] or "",
+            specSha256=spec["specSha256"],
+        )
+        for key, value in spec["environmentVariables"].items():
+            env_keys.append(_b64(key))
+            env_values.append(_b64(value))
+
+    replacements = {
+        "__APP_ROOT__": APP_ROOT,
+        "__APP_SCHEMA_VERSION__": str(APP_SCHEMA_VERSION),
+        "__NETWORK_NAME__": NETWORK_NAME,
+        "__CADDY_CONTAINER__": CADDY_CONTAINER,
+        "__DESIRED_PRESENT__": "true" if spec is not None else "false",
+        "__D_OWNER_B64__": _b64(desired["ownerRepo"]),
+        "__D_ENV_B64__": _b64(desired["environment"]),
+        "__D_APP_B64__": _b64(desired["appSlug"]),
+        "__D_CONTAINER_B64__": _b64(desired["containerName"]),
+        "__D_IMAGE_B64__": _b64(desired["image"]),
+        "__D_PORT__": desired["runtimePort"],
+        "__D_HEALTH_B64__": _b64(desired["healthPath"]),
+        "__D_RUN_AS_B64__": _b64(desired["runAs"]),
+        "__D_PERSISTENCE__": desired["persistenceMode"],
+        "__D_DATA_TARGET_B64__": _b64(desired["dataContainerPath"]),
+        "__D_SPEC_SHA__": desired["specSha256"],
+        "__D_ENV_KEYS__": " ".join(f"'{item}'" for item in env_keys),
+        "__D_ENV_VALUES__": " ".join(f"'{item}'" for item in env_values),
+    }
+    script = REMOTE_SCRIPT
+    for placeholder, value in replacements.items():
+        script = script.replace(placeholder, value)
+    if "__" in script:
+        raise DeploymentKitError("Internal application-runtime script contains an unresolved placeholder.")
+    return script
+
+
+def _parse_inventory(output: str) -> dict[str, Any]:
+    apps: list[dict[str, Any]] = []
+    summary: dict[str, str] = {}
+    for raw in output.splitlines():
+        if not raw:
+            continue
+        parts = raw.split("\t")
+        if parts[0] == "SUMMARY":
+            if len(parts) != 3 or parts[1] in summary:
+                raise DeploymentKitError("Malformed or duplicate application inventory summary.")
+            summary[parts[1]] = parts[2]
+            continue
+        if parts[0] != "APP" or len(parts) != 15:
+            raise DeploymentKitError("Malformed application inventory record.")
+        try:
+            port = int(parts[7])
+        except ValueError as error:
+            raise DeploymentKitError("Malformed application inventory runtime port.") from error
+        if parts[12] not in {"true", "false"} or parts[13] not in {"true", "false"}:
+            raise DeploymentKitError("Malformed application inventory boolean value.")
+        owner = _owner_repo(parts[1])
+        environment = _slug(parts[2], "environment")
+        app_slug = _slug(parts[3], "appSlug")
+        container = _container_name(parts[4])
+        image = _image(parts[5])
+        if re.fullmatch(r"[0-9a-f]{64}", parts[6]) is None:
+            raise DeploymentKitError("Malformed application inventory spec fingerprint.")
+        health_path = _health_path(parts[8])
+        if parts[9] not in {"none", "directory"}:
+            raise DeploymentKitError("Malformed application inventory persistence mode.")
+        app = {
+            "ownerRepo": owner,
+            "environment": environment,
+            "appSlug": app_slug,
+            "containerName": container,
+            "image": image,
+            "specSha256": parts[6],
+            "runtimePort": port,
+            "healthPath": health_path,
+            "persistenceMode": parts[9],
+            "currentRelease": parts[10] or None,
+            "previousRelease": parts[11] or None,
+            "containerRunning": parts[12] == "true",
+            "connectedToSharedNetwork": parts[13] == "true",
+            "httpHealthy": parts[14] == "true",
+        }
+        apps.append(app)
+    if set(summary) != {"appCount"}:
+        raise DeploymentKitError("Application inventory omitted appCount.")
+    try:
+        count = int(summary["appCount"])
+    except ValueError as error:
+        raise DeploymentKitError("Malformed application inventory count.") from error
+    if count != len(apps):
+        raise DeploymentKitError("Application inventory count does not match records.")
+    keys = [(item["appSlug"], item["environment"]) for item in apps]
+    if len(keys) != len(set(keys)):
+        raise DeploymentKitError("Duplicate application/environment ownership records were reported.")
+    return {"applications": sorted(apps, key=lambda item: (item["appSlug"], item["environment"]))}
+
+
+def _run_remote(
+    profile: dict[str, Any],
+    address: str,
+    action: str,
+    *,
+    spec: dict[str, Any] | None = None,
+    expected_spec_sha: str = "",
+) -> str:
+    if action not in {"inventory", "deploy"}:
+        raise DeploymentKitError(f"Unsupported application-runtime action: {action}")
+    args = [action]
+    if action == "deploy":
+        args.extend([expected_spec_sha or "NONE", profile["user"]])
+    command = ssh_args(
+        profile,
+        address,
+        command="sudo -n bash -s -- " + " ".join(args),
+    )
+    completed = subprocess.run(
+        command,
+        input=build_remote_script(spec).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 application-runtime {action} failed: {detail}")
+    return stdout
+
+
+def app_inventory(name: str) -> dict[str, Any]:
+    profile = load_profile(name)
+    evidence = verify_access(profile)
+    inventory = _parse_inventory(
+        _run_remote(profile, evidence["address"], "inventory")
+    )
+    inventory["targetName"] = name
+    inventory["verifiedAddress"] = evidence["address"]
+    inventory["mutated"] = False
+    return inventory
+
+
+def _inventory_snapshot(inventory: dict[str, Any]) -> str:
+    value = {"applications": inventory["applications"]}
+    return hashlib.sha256(
+        json.dumps(value, sort_keys=True, separators=(",", ":")).encode("utf-8")
+    ).hexdigest()
+
+
+def _find_app(inventory: dict[str, Any], app_slug: str, environment: str) -> dict[str, Any] | None:
+    return next(
+        (
+            item
+            for item in inventory["applications"]
+            if item["appSlug"] == app_slug and item["environment"] == environment
+        ),
+        None,
+    )
+
+
+def plan_app_deploy(name: str, spec: dict[str, Any]) -> dict[str, Any]:
+    platform = platform_status(name)
+    if platform["state"] != "ready":
+        raise DeploymentKitError(
+            f"Application deployment requires a ready shared platform; target '{name}' is '{platform['state']}'."
+        )
+    inventory = app_inventory(name)
+    existing = _find_app(inventory, spec["appSlug"], spec["environment"])
+    if existing is not None and existing["ownerRepo"] != spec["ownerRepo"]:
+        raise DeploymentKitError("Application/environment ownership does not match the requested repository.")
+    for item in inventory["applications"]:
+        if (
+            item["containerName"] == spec["containerName"]
+            and (item["appSlug"], item["environment"])
+            != (spec["appSlug"], spec["environment"])
+        ):
+            raise DeploymentKitError(
+                f"Container name collision with managed app {item['appSlug']}--{item['environment']}."
+            )
+    if (
+        existing is not None
+        and existing["specSha256"] == spec["specSha256"]
+        and existing["containerRunning"]
+        and existing["connectedToSharedNetwork"]
+        and existing["httpHealthy"]
+    ):
+        raise DeploymentKitError("The exact application runtime spec is already deployed and healthy.")
+    return {
+        "targetName": name,
+        "action": "deploy",
+        "environment": spec["environment"],
+        "appSlug": spec["appSlug"],
+        "ownerRepo": spec["ownerRepo"],
+        "containerName": spec["containerName"],
+        "image": spec["image"],
+        "runtimePort": spec["runtimePort"],
+        "healthPath": spec["healthPath"],
+        "persistenceMode": spec["persistence"]["mode"],
+        "changeType": "update" if existing is not None else "create",
+        "previousImage": existing["image"] if existing is not None else None,
+        "previousRelease": existing["currentRelease"] if existing is not None else None,
+        "retainsPreviousRelease": existing is not None,
+        "publishesHostPort": False,
+        "attachesSharedNetwork": NETWORK_NAME,
+        "modifiesRoutes": False,
+        "persistentDataDeletion": False,
+        "inventorySnapshot": _inventory_snapshot(inventory),
+        "expectedSpecSha256": existing["specSha256"] if existing is not None else None,
+        "spec": spec,
+    }
+
+
+def deploy_write_phrase(plan: dict[str, Any]) -> str:
+    return (
+        PRODUCTION_APP_DEPLOY_WRITE_PHRASE
+        if plan["environment"] == "production"
+        else APP_DEPLOY_WRITE_PHRASE
+    )
+
+
+def apply_app_deploy(plan: dict[str, Any]) -> dict[str, Any]:
+    required = {
+        "targetName",
+        "action",
+        "environment",
+        "appSlug",
+        "ownerRepo",
+        "containerName",
+        "image",
+        "runtimePort",
+        "healthPath",
+        "persistenceMode",
+        "changeType",
+        "previousImage",
+        "previousRelease",
+        "retainsPreviousRelease",
+        "publishesHostPort",
+        "attachesSharedNetwork",
+        "modifiesRoutes",
+        "persistentDataDeletion",
+        "inventorySnapshot",
+        "expectedSpecSha256",
+        "spec",
+    }
+    if not isinstance(plan, dict) or set(plan) != required or plan["action"] != "deploy":
+        raise DeploymentKitError("Malformed application deployment plan.")
+
+    current = app_inventory(plan["targetName"])
+    if _inventory_snapshot(current) != plan["inventorySnapshot"]:
+        raise DeploymentKitError(
+            "Application inventory changed after the plan was reviewed; create and authorize a fresh plan."
+        )
+    platform = platform_status(plan["targetName"])
+    if platform["state"] != "ready":
+        raise DeploymentKitError("Shared host platform is no longer ready; application deployment is blocked.")
+
+    profile = load_profile(plan["targetName"])
+    evidence = verify_access(profile)
+    _run_remote(
+        profile,
+        evidence["address"],
+        "deploy",
+        spec=plan["spec"],
+        expected_spec_sha=plan["expectedSpecSha256"] or "",
+    )
+    final = app_inventory(plan["targetName"])
+    deployed = _find_app(final, plan["appSlug"], plan["environment"])
+    if deployed is None:
+        raise DeploymentKitError("Application deployment returned without managed runtime state.")
+    if deployed["specSha256"] != plan["spec"]["specSha256"]:
+        raise DeploymentKitError("Application deployment returned with a different runtime spec.")
+    if not (
+        deployed["containerRunning"]
+        and deployed["connectedToSharedNetwork"]
+        and deployed["httpHealthy"]
+    ):
+        raise DeploymentKitError("Application deployment completed but runtime readiness is not healthy.")
+    final["mutated"] = True
+    return final