@mriekki/project-forge 3.0.0 → 4.1.0

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

@@ -10,9 +10,10 @@ import subprocess
 from typing import Any
 
 from .app_runtime import normalize_app_spec, plan_app_deploy
-from .app_runtime_workstation import apply_app_deploy_from_workstation
+from .app_runtime_workstation import apply_app_deploy_with_preloaded_image
 from .box_platform import platform_status
 from .errors import DeploymentKitError
+from .image_transfer import remote_image_present, transfer_image, verify_local_image
 from .registry_access import normalize_registry_image
 from .teardown import tear_down_project
 
@@ -123,10 +124,66 @@ def plan_environment_proof(
         "requiredAuthorization": (
             PRODUCTION_ENVIRONMENT_PROOF_WRITE_PHRASE if production else ENVIRONMENT_PROOF_WRITE_PHRASE
         ),
+    }
+
+
+def _proof_result(plan: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "targetName": plan["targetName"],
+        "ownerRepo": plan["ownerRepo"],
+        "environment": plan["environment"],
+        "production": plan["production"],
+        "probeAppSlug": plan["probeAppSlug"],
+        "probeImageTag": plan["probeImageTag"],
+        "preflight": {
+            "targetAccess": "verified-by-platform-doctor",
+            "hostPlatform": "ready",
+        },
+        "registryDigest": None,
+        "localImageId": None,
+        "transferState": "not-started",
+        "remoteImageId": None,
+        "runtimeState": "not-started",
+        "httpHealth": "not-run",
+        "cleanupState": "not-run",
+        "imageCacheState": "unknown",
+        "proof": "failed",
         "mutated": False,
+        "finalMutationState": "none",
+        "error": None,
+        "cleanupError": None,
     }
 
 
+def _cleanup_state(cleanup: dict[str, Any] | None, environment: str) -> str:
+    if not isinstance(cleanup, dict):
+        return "unknown"
+    entry = next(
+        (item for item in cleanup.get("environments", []) if item.get("environment") == environment),
+        None,
+    )
+    if not isinstance(entry, dict):
+        return "unknown"
+    state = entry.get("runtimeAndPersistentData", {}).get("state")
+    return state if isinstance(state, str) and state else "unknown"
+
+
+def _final_mutation_state(result: dict[str, Any]) -> str:
+    cleanup = result["cleanupState"]
+    cache = result["imageCacheState"]
+    if cleanup not in {"removed", "absent", "not-run"}:
+        return "cleanup-incomplete"
+    if cache == "present":
+        return "runtime-clean-image-cached"
+    if result["mutated"] and cache == "absent":
+        return "clean"
+    if result["mutated"]:
+        return "runtime-clean-cache-unknown"
+    if result["transferState"] == "attempting" and cache == "unknown":
+        return "mutation-unknown-after-transfer-attempt"
+    return "none"
+
+
 def run_environment_proof(plan: dict[str, Any]) -> dict[str, Any]:
     required = {
         "targetName",
@@ -140,89 +197,105 @@ def run_environment_proof(plan: dict[str, Any]) -> dict[str, Any]:
         "healthPath",
         "cleanup",
         "requiredAuthorization",
-        "mutated",
     }
-    if not isinstance(plan, dict) or set(plan) != required or plan["mutated"] is not False:
+    if not isinstance(plan, dict) or set(plan) != required:
         raise DeploymentKitError("Malformed environment proof plan.")
 
-    exact_image = _resolve_probe_image(plan["probeImageTag"])
-    spec = normalize_app_spec(
-        owner_repo=plan["ownerRepo"],
-        environment=plan["environment"],
-        app_slug=plan["probeAppSlug"],
-        container_name=f"{plan['probeAppSlug']}--{plan['environment']}",
-        image=exact_image,
-        runtime_port=80,
-        health_path=plan["healthPath"],
-        run_as="0",
-        persistence_mode="none",
-        data_container_path=None,
-        environment_variables={},
-    )
-    deploy_plan = plan_app_deploy(plan["targetName"], spec)
-
+    result = _proof_result(plan)
+    deploy_plan: dict[str, Any] | None = None
+    transfer: dict[str, Any] | None = None
     deployment: dict[str, Any] | None = None
     cleanup: dict[str, Any] | None = None
-    deploy_error: Exception | None = None
-    cleanup_error: Exception | None = None
+    operation_error: Exception | None = None
+
     try:
-        deployment = apply_app_deploy_from_workstation(deploy_plan)
-    except Exception as error:  # cleanup must still be attempted after a partially applied proof
-        deploy_error = error
+        exact_image = _resolve_probe_image(plan["probeImageTag"])
+        result["registryDigest"] = exact_image
+        local = verify_local_image(exact_image)
+        result["localImageId"] = local["localImageId"]
+
+        spec = normalize_app_spec(
+            owner_repo=plan["ownerRepo"],
+            environment=plan["environment"],
+            app_slug=plan["probeAppSlug"],
+            container_name=f"{plan['probeAppSlug']}--{plan['environment']}",
+            image=exact_image,
+            runtime_port=80,
+            health_path=plan["healthPath"],
+            run_as="0",
+            persistence_mode="none",
+            data_container_path=None,
+            environment_variables={},
+        )
+        deploy_plan = plan_app_deploy(plan["targetName"], spec)
+
+        result["transferState"] = "attempting"
+        transfer = transfer_image(plan["targetName"], exact_image)
+        result["transferState"] = transfer["status"]
+        result["remoteImageId"] = transfer["remoteImageId"]
+        result["mutated"] = bool(transfer["mutated"])
+
+        result["runtimeState"] = "applying"
+        deployment = apply_app_deploy_with_preloaded_image(deploy_plan, transfer)
+        result["runtimeState"] = "healthy"
+        result["httpHealth"] = "passed"
+        result["mutated"] = True
+    except Exception as error:  # terminal proof evidence must survive operational failure
+        operation_error = error
+        result["error"] = str(error)
+        if result["runtimeState"] == "applying":
+            result["runtimeState"] = "failed-or-partial"
+            result["httpHealth"] = "failed-or-not-reached"
     finally:
-        try:
-            cleanup = tear_down_project(
-                {
-                    "ownerRepo": plan["ownerRepo"],
-                    "appSlug": plan["probeAppSlug"],
-                    "scope": plan["environment"],
-                    "environmentTargets": {plan["environment"]: plan["targetName"]},
-                    "localPackage": None,
-                    "productionEnvironments": [plan["environment"]] if plan["production"] else [],
-                }
-            )
-        except Exception as error:
-            cleanup_error = error
-
-    if deploy_error is not None:
-        detail = str(deploy_error)
-        if cleanup_error is not None:
-            detail += f" Cleanup also failed: {cleanup_error}"
-        raise DeploymentKitError(f"Environment proof deployment failed: {detail}") from deploy_error
-    if cleanup_error is not None:
-        raise DeploymentKitError(
-            f"Environment proof deployment succeeded but cleanup failed: {cleanup_error}"
-        ) from cleanup_error
-    assert deployment is not None and cleanup is not None
-
-    matched = next(
-        (
-            item
-            for item in deployment.get("applications", [])
-            if item.get("appSlug") == plan["probeAppSlug"]
-            and item.get("environment") == plan["environment"]
-        ),
-        None,
-    )
-    if not matched or not matched.get("containerRunning") or not matched.get("httpHealthy"):
-        raise DeploymentKitError("Environment proof returned without healthy disposable runtime evidence.")
-    cleanup_entry = next(
-        (item for item in cleanup.get("environments", []) if item.get("environment") == plan["environment"]),
-        None,
-    )
-    if cleanup_entry is None or cleanup_entry.get("runtimeAndPersistentData", {}).get("state") not in {"removed", "absent"}:
-        raise DeploymentKitError("Environment proof cleanup did not return terminal runtime cleanup evidence.")
+        if deploy_plan is not None:
+            try:
+                cleanup = tear_down_project(
+                    {
+                        "ownerRepo": plan["ownerRepo"],
+                        "appSlug": plan["probeAppSlug"],
+                        "scope": plan["environment"],
+                        "environmentTargets": {plan["environment"]: plan["targetName"]},
+                        "localPackage": None,
+                        "productionEnvironments": [plan["environment"]] if plan["production"] else [],
+                    }
+                )
+                result["cleanupState"] = _cleanup_state(cleanup, plan["environment"])
+                if result["cleanupState"] == "removed":
+                    result["mutated"] = True
+            except Exception as error:
+                result["cleanupState"] = "failed"
+                result["cleanupError"] = str(error)
 
-    return {
-        "targetName": plan["targetName"],
-        "ownerRepo": plan["ownerRepo"],
-        "environment": plan["environment"],
-        "production": plan["production"],
-        "probeAppSlug": plan["probeAppSlug"],
-        "probeImage": exact_image,
-        "artifactDelivery": "workstation-transfer",
-        "runtimeHealthy": True,
-        "cleanupState": cleanup_entry["runtimeAndPersistentData"]["state"],
-        "proof": "passed",
-        "mutated": True,
-    }
+        image_id = result.get("localImageId")
+        if isinstance(image_id, str):
+            try:
+                cached = remote_image_present(plan["targetName"], image_id)
+                result["imageCacheState"] = "present" if cached else "absent"
+                if cached:
+                    result["remoteImageId"] = image_id
+                    if result["transferState"] == "attempting":
+                        result["mutated"] = True
+            except Exception:
+                result["imageCacheState"] = "unknown"
+
+    cleanup_terminal = result["cleanupState"] in {"removed", "absent"}
+    if operation_error is None and result["cleanupError"] is None and cleanup_terminal:
+        assert deployment is not None
+        matched = next(
+            (
+                item
+                for item in deployment.get("applications", [])
+                if item.get("appSlug") == plan["probeAppSlug"]
+                and item.get("environment") == plan["environment"]
+            ),
+            None,
+        )
+        if matched and matched.get("containerRunning") and matched.get("httpHealthy"):
+            result["proof"] = "passed"
+        else:
+            result["error"] = "Environment proof returned without healthy disposable runtime evidence."
+    elif operation_error is None and result["cleanupError"] is None and not cleanup_terminal:
+        result["error"] = "Environment proof cleanup did not return terminal runtime cleanup evidence."
+
+    result["finalMutationState"] = _final_mutation_state(result)
+    return result

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

@@ -0,0 +1,241 @@
+"""Read-only orchestration for one remote Project Forge setup target.
+
+This module intentionally composes existing deterministic primitives without applying
+mutations. It gives conversational front ends one state machine to render instead of
+reconstructing profile, SSH, host-platform, and proof readiness themselves.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .box_platform import platform_doctor
+from .doctor import target_doctor, workstation_doctor
+from .environment_probe import plan_environment_proof
+from .errors import DeploymentKitError
+from .profiles import load_profile
+from .ssh import verify_access
+
+
+READINESS_ORDER = (
+    "workspace",
+    "targetDefinition",
+    "targetAccess",
+    "hostPlatform",
+    "deploymentPath",
+    "application",
+)
+
+
+def _phase(label: str, state: str, *, detail: Any = None) -> dict[str, Any]:
+    value: dict[str, Any] = {"label": label, "state": state}
+    if detail is not None:
+        value["detail"] = detail
+    return value
+
+
+def remote_setup_status(name: str) -> dict[str, Any]:
+    """Return one read-only, terminal status model for remote environment setup."""
+
+    workstation = workstation_doctor()
+    target = target_doctor(name)
+
+    phases: dict[str, dict[str, Any]] = {
+        "workspace": _phase(
+            "WORKSPACE READY",
+            "ready" if workstation["state"] in {"configured", "partially-configured"} else workstation["state"],
+            detail=workstation,
+        ),
+        "targetDefinition": _phase(
+            "TARGET DEFINITION READY",
+            "ready" if target["state"] != "needs-profile" else "needs-profile",
+            detail=target,
+        ),
+        "targetAccess": _phase("TARGET ACCESS READY", "blocked"),
+        "hostPlatform": _phase("HOST PLATFORM READY", "blocked"),
+        "deploymentPath": _phase("DEPLOYMENT PATH PROVEN", "not-proven"),
+        "application": _phase("APPLICATION DEPLOYED", "not-part-of-setup"),
+    }
+
+    target_access: dict[str, Any] | None = None
+    host_platform: dict[str, Any] | None = None
+
+    if target["state"] == "ready-to-verify":
+        try:
+            target_access = verify_access(load_profile(name))
+            phases["targetAccess"] = _phase("TARGET ACCESS READY", "ready", detail=target_access)
+        except DeploymentKitError as error:
+            phases["targetAccess"] = _phase(
+                "TARGET ACCESS READY",
+                "verification-failed",
+                detail={"reason": str(error)},
+            )
+    elif target["state"] == "needs-profile":
+        phases["targetAccess"] = _phase("TARGET ACCESS READY", "blocked-by-target-definition")
+    else:
+        phases["targetAccess"] = _phase(
+            "TARGET ACCESS READY",
+            f"blocked-by-{target['state']}",
+            detail={"nextAction": target.get("nextAction")},
+        )
+
+    if phases["targetAccess"]["state"] == "ready":
+        try:
+            host_platform = platform_doctor(name)
+            phases["hostPlatform"] = _phase(
+                "HOST PLATFORM READY",
+                "ready" if host_platform["state"] == "ready" else host_platform["state"],
+                detail=host_platform,
+            )
+        except DeploymentKitError as error:
+            phases["hostPlatform"] = _phase(
+                "HOST PLATFORM READY",
+                "inspection-failed",
+                detail={"reason": str(error)},
+            )
+    else:
+        phases["hostPlatform"] = _phase("HOST PLATFORM READY", "blocked-by-target-access")
+
+    current = next(
+        (key for key in READINESS_ORDER if phases[key]["state"] not in {"ready", "not-part-of-setup"}),
+        "application",
+    )
+    return {
+        "targetName": name,
+        "state": "host-platform-ready" if phases["hostPlatform"]["state"] == "ready" else "needs-setup",
+        "currentPhase": current,
+        "phases": phases,
+        "mutated": False,
+    }
+
+
+def _next_action(status: dict[str, Any]) -> dict[str, Any]:
+    phases = status["phases"]
+    target = phases["targetDefinition"].get("detail") or {}
+
+    if phases["targetDefinition"]["state"] == "needs-profile":
+        return {
+            "kind": "missing-facts",
+            "action": "configure-target-profile",
+            "command": f"project-forge-deploy target configure {status['targetName']} <target facts>",
+            "reason": "A target profile does not exist yet; host/user/SSH facts must come from the developer or portable profile.",
+        }
+
+    target_state = target.get("state")
+    if target_state == "needs-key":
+        return {
+            "kind": "write-gated",
+            "action": "create-or-select-key",
+            "command": f"project-forge-deploy target key-create {status['targetName']}",
+            "authorization": "[LOCAL KEY WRITE]",
+        }
+    if target_state == "needs-trust":
+        return {
+            "kind": "human-verification",
+            "action": "verify-and-enroll-host-trust",
+            "command": f"project-forge-deploy target trust-candidates {status['targetName']}",
+            "reason": "Host-key trust requires an independently observed target-console fingerprint before enrollment.",
+        }
+    if target_state == "needs-address":
+        return {
+            "kind": "missing-facts",
+            "action": "set-verified-address",
+            "command": f"project-forge-deploy target address-set {status['targetName']} --address <verified-address>",
+            "reason": "Stable host identity exists but no usable address resolved; use only a separately verified current address.",
+        }
+    if target_state == "blocked":
+        return {
+            "kind": "blocked",
+            "action": target.get("nextAction", "repair-target-profile"),
+            "reason": target.get("reason", "Target definition is blocked."),
+        }
+
+    if phases["targetAccess"]["state"] != "ready":
+        return {
+            "kind": "read-only",
+            "action": "verify-target-access",
+            "command": f"project-forge-deploy target verify {status['targetName']}",
+            "reason": (phases["targetAccess"].get("detail") or {}).get("reason"),
+        }
+
+    platform = phases["hostPlatform"].get("detail") or {}
+    platform_state = phases["hostPlatform"]["state"]
+    if platform_state == "installable":
+        return {
+            "kind": "write-gated",
+            "action": "install-host-platform",
+            "command": f"project-forge-deploy platform install {status['targetName']}",
+            "authorization": "[HOST PLATFORM WRITE]",
+        }
+    if platform_state == "upgrade-required":
+        return {
+            "kind": "write-gated",
+            "action": "upgrade-host-platform",
+            "command": f"project-forge-deploy platform upgrade {status['targetName']}",
+            "authorization": "[HOST PLATFORM WRITE]",
+        }
+    if platform_state in {"blocked-port-80", "drifted", "blocked", "incompatible", "inspection-failed"}:
+        return {
+            "kind": "blocked",
+            "action": platform.get("nextAction", "inspect-host-platform"),
+            "reason": platform.get("reason", f"Host platform state is {platform_state}."),
+            "safety": "Inspect exact ownership/state first; do not broadly prune or take over unrelated host resources.",
+        }
+    if platform_state != "ready":
+        return {
+            "kind": "blocked",
+            "action": "inspect-host-platform",
+            "reason": f"Host platform state is {platform_state}.",
+        }
+
+    return {
+        "kind": "proof-context-required",
+        "action": "plan-deployment-path-proof",
+        "reason": "Target access and host platform are ready. Owner/repository and logical environment are needed to plan the disposable proof.",
+    }
+
+
+def remote_setup_plan(
+    name: str,
+    *,
+    owner_repo: str | None = None,
+    environment: str | None = None,
+    production: bool = False,
+) -> dict[str, Any]:
+    """Return the exact next deterministic setup action without mutating state."""
+
+    status = remote_setup_status(name)
+    next_action = _next_action(status)
+
+    if (
+        next_action["action"] == "plan-deployment-path-proof"
+        and owner_repo is not None
+        and environment is not None
+    ):
+        proof = plan_environment_proof(
+            name,
+            owner_repo=owner_repo,
+            environment=environment,
+            production=production,
+        )
+        command = (
+            f"project-forge-deploy environment proof plan {name} "
+            f"--owner-repo {proof['ownerRepo']} --environment {proof['environment']}"
+        )
+        if production:
+            command += " --production"
+        next_action = {
+            "kind": "read-only",
+            "action": "review-deployment-path-proof",
+            "command": command,
+            "proofPlan": proof,
+            "runAuthorization": proof["requiredAuthorization"],
+        }
+    elif (owner_repo is None) != (environment is None):
+        raise DeploymentKitError("ownerRepo and environment must be supplied together for setup proof planning.")
+
+    return {
+        **status,
+        "next": next_action,
+        "mutated": False,
+    }

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

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import re
 import shlex
 import shutil
 import subprocess
@@ -13,6 +14,9 @@ from .registry_access import normalize_registry_image
 from .ssh import ssh_args, verify_access
 
 
+_IMAGE_ID_RE = re.compile(r"^sha256:[0-9a-f]{64}$")
+
+
 def _docker() -> str:
     path = shutil.which("docker")
     if path is None:
@@ -20,13 +24,25 @@ def _docker() -> str:
     return path
 
 
+def _image_id(value: str) -> str:
+    if not isinstance(value, str) or _IMAGE_ID_RE.fullmatch(value) is None:
+        raise DeploymentKitError("Docker image ID must be sha256:<64 lowercase hex>.")
+    return value
+
+
 def verify_local_image(image: str) -> dict[str, str]:
+    """Verify the declared immutable registry digest and resolve its local config/image ID.
+
+    Registry RepoDigests are release identity. Docker's image ID is the config digest and is
+    the content identity preserved by ``docker save``/``docker load`` even when RepoTags are
+    absent from the archive.
+    """
+
     exact = normalize_registry_image(image)
     result = subprocess.run(
-        [_docker(), "image", "inspect", exact],
+        [_docker(), "image", "inspect", "--format", "{{.Id}}", exact],
         check=False,
-        stdout=subprocess.DEVNULL,
-        stderr=subprocess.PIPE,
+        capture_output=True,
         text=True,
         encoding="utf-8",
         errors="replace",
@@ -36,11 +52,17 @@ def verify_local_image(image: str) -> dict[str, str]:
             f"Exact image is not present in the workstation Docker engine: {exact}. "
             "Pull/build it locally before transfer."
         )
-    return {"image": exact, "localImage": "verified"}
+    image_id = _image_id(result.stdout.strip())
+    return {
+        "image": exact,
+        "registryDigest": exact,
+        "localImageId": image_id,
+    }
 
 
-def _remote_has_image(profile: dict[str, Any], address: str, image: str) -> bool:
-    command = "sudo -n docker image inspect " + shlex.quote(image) + " >/dev/null 2>&1"
+def _remote_has_image(profile: dict[str, Any], address: str, image_id: str) -> bool:
+    exact_id = _image_id(image_id)
+    command = "sudo -n docker image inspect " + shlex.quote(exact_id) + " >/dev/null 2>&1"
     result = subprocess.run(
         ssh_args(profile, address, command=command),
         check=False,
@@ -50,17 +72,31 @@ def _remote_has_image(profile: dict[str, Any], address: str, image: str) -> bool
     return result.returncode == 0
 
 
+def remote_image_present(name: str, image_id: str) -> bool:
+    """Read-only check for one exact Docker config/image ID on a verified target."""
+
+    exact_id = _image_id(image_id)
+    profile = load_profile(name)
+    access = verify_access(profile)
+    return _remote_has_image(profile, access["address"], exact_id)
+
+
 def transfer_image(name: str, image: str) -> dict[str, Any]:
-    exact = normalize_registry_image(image)
-    verify_local_image(exact)
+    local = verify_local_image(image)
+    exact = local["registryDigest"]
+    image_id = local["localImageId"]
     profile = load_profile(name)
     access = verify_access(profile)
     address = access["address"]
 
-    if _remote_has_image(profile, address, exact):
+    if _remote_has_image(profile, address, image_id):
         return {
             "targetName": name,
             "image": exact,
+            "registryDigest": exact,
+            "localImageId": image_id,
+            "remoteImageId": image_id,
+            "runtimeImage": image_id,
             "status": "already-present",
             "mutated": False,
         }
@@ -93,13 +129,17 @@ def transfer_image(name: str, image: str) -> dict[str, Any]:
         )
         raise DeploymentKitError(f"Remote Docker image load failed: {detail}")
 
-    if not _remote_has_image(profile, address, exact):
+    if not _remote_has_image(profile, address, image_id):
         raise DeploymentKitError(
-            "Remote docker load completed but the exact immutable image reference is not inspectable on the target."
+            "Remote docker load completed but the exact Docker config/image ID is not inspectable on the target."
         )
     return {
         "targetName": name,
         "image": exact,
+        "registryDigest": exact,
+        "localImageId": image_id,
+        "remoteImageId": image_id,
+        "runtimeImage": image_id,
         "status": "transferred",
         "mutated": True,
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mriekki/project-forge",
-  "version": "3.0.0",
+  "version": "4.1.0",
   "description": "Public consumer distribution and updater for Project Forge engineering assets.",
   "type": "module",
   "bin": {