@mriekki/project-forge 4.0.0 → 4.2.0

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

@@ -10,9 +10,11 @@ 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 .proof_receipt import write_environment_proof_receipt
 from .registry_access import normalize_registry_image
 from .teardown import tear_down_project
 
@@ -123,10 +125,68 @@ 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,
+        "receipt": None,
+        "receiptError": 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 +200,109 @@ 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)
+    try:
+        result["receipt"] = write_environment_proof_receipt(result)
+    except Exception as error:  # proof result stays truthful even if local evidence persistence fails
+        result["receiptError"] = str(error)
+    return result

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

@@ -0,0 +1,323 @@
+"""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 .proof_receipt import load_environment_proof_receipt
+from .ssh import diagnose_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 _current_phase(phases: dict[str, dict[str, Any]]) -> str:
+    return next(
+        (key for key in READINESS_ORDER if phases[key]["state"] not in {"ready", "proven", "not-part-of-setup"}),
+        "application",
+    )
+
+
+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"),
+    }
+
+    host_platform: dict[str, Any] | None = None
+
+    if target["state"] == "ready-to-verify":
+        target_access = diagnose_access(load_profile(name))
+        phases["targetAccess"] = _phase(
+            "TARGET ACCESS READY",
+            "ready" if target_access["state"] == "verified" else "diagnosis-required",
+            detail=target_access,
+        )
+    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")
+
+    return {
+        "targetName": name,
+        "state": "host-platform-ready" if phases["hostPlatform"]["state"] == "ready" else "needs-setup",
+        "currentPhase": _current_phase(phases),
+        "phases": phases,
+        "mutated": False,
+    }
+
+
+def _access_recovery(status: dict[str, Any]) -> dict[str, Any]:
+    detail = status["phases"]["targetAccess"].get("detail") or {}
+    category = detail.get("failureCategory")
+    target = status["targetName"]
+    command = f"project-forge-deploy environment setup status {target} --json"
+
+    if category in {"remote-authentication-rejected", "remote-account-policy-rejected"}:
+        return {
+            "kind": "operator-action-required",
+            "action": "inspect-remote-account-access-policy",
+            "command": command,
+            "reason": detail.get("guidance"),
+            "safety": (
+                "Use a trusted target console or already-authorized administrative session. "
+                "Do not reinstall keys repeatedly, enable password SSH, widen AllowUsers, or weaken host verification implicitly."
+            ),
+        }
+    if category == "local-signing-failed":
+        return {
+            "kind": "local-repair",
+            "action": "repair-local-key-signing",
+            "command": command,
+            "reason": detail.get("guidance"),
+        }
+    if category == "host-identity-rejected":
+        return {
+            "kind": "human-verification",
+            "action": "reverify-host-identity",
+            "command": f"project-forge-deploy target trust-candidates {target}",
+            "reason": detail.get("guidance"),
+        }
+    if category in {"transport-failed", "name-resolution-failed"}:
+        return {
+            "kind": "missing-facts",
+            "action": "repair-target-address-or-network-path",
+            "command": command,
+            "reason": detail.get("guidance") or detail.get("reason"),
+        }
+    if category == "missing-identity":
+        return {
+            "kind": "write-gated",
+            "action": "create-or-select-key",
+            "command": f"project-forge-deploy target key-create {target}",
+            "authorization": "[LOCAL KEY WRITE]",
+            "reason": detail.get("reason"),
+        }
+    if category == "missing-trust":
+        return {
+            "kind": "human-verification",
+            "action": "verify-and-enroll-host-trust",
+            "command": f"project-forge-deploy target trust-candidates {target}",
+            "reason": detail.get("reason"),
+        }
+    return {
+        "kind": "read-only",
+        "action": "diagnose-target-access",
+        "command": command,
+        "reason": detail.get("guidance") or detail.get("reason"),
+    }
+
+
+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 _access_recovery(status)
+
+    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}.",
+        }
+
+    if phases["deploymentPath"]["state"] == "proven":
+        return {
+            "kind": "complete",
+            "action": "remote-environment-ready",
+            "reason": "Fresh workstation-local proof evidence matches this Project/environment/target context.",
+            "proofReceipt": phases["deploymentPath"].get("detail"),
+        }
+
+    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."""
+
+    if (owner_repo is None) != (environment is None):
+        raise DeploymentKitError("ownerRepo and environment must be supplied together for setup proof planning.")
+
+    status = remote_setup_status(name)
+    if owner_repo is not None and environment is not None and status["phases"]["hostPlatform"]["state"] == "ready":
+        receipt = load_environment_proof_receipt(
+            name,
+            owner_repo=owner_repo,
+            environment=environment,
+            production=production,
+        )
+        status["phases"]["deploymentPath"] = _phase(
+            "DEPLOYMENT PATH PROVEN",
+            "proven" if receipt["state"] == "proven" else "not-proven",
+            detail=receipt,
+        )
+        status["currentPhase"] = _current_phase(status["phases"])
+        if receipt["state"] == "proven":
+            status["state"] = "environment-ready"
+
+    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"],
+            "previousProof": status["phases"]["deploymentPath"].get("detail"),
+        }
+
+    return {
+        **status,
+        "next": next_action,
+        "mutated": False,
+    }

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

@@ -14,7 +14,7 @@ from .keys import key_fingerprint, public_key_info, required_tool as required_ss
 from .portable_profile import _machine_paths
 from .profiles import load_profile, save_profile, target_profile_path, validate_profile, validate_target_name
 from .security import check_identity_security, prepare_ssh_directory, validate_target_trust_file
-from .ssh import verify_access
+from .ssh import probe_authentication_methods, resolve_addresses, verify_access
 
 
 HOME_LAB_BOOTSTRAP_PHRASE = "[HOME LAB ACCESS BOOTSTRAP]"
@@ -212,6 +212,23 @@ def _password_bootstrap_args(profile: dict[str, Any], *, first_use: bool, comman
     ]
 
 
+def _require_password_bootstrap_capability(profile: dict[str, Any]) -> list[dict[str, Any]]:
+    """Fail before password onboarding when a trusted server advertises key-only auth."""
+
+    evidence = [probe_authentication_methods(profile, address) for address in resolve_addresses(profile)]
+    observed = [item for item in evidence if item["observed"]]
+    if observed and not any(item["passwordSupported"] for item in observed):
+        advertised = sorted({method for item in observed for method in item["methods"]})
+        shown = ", ".join(advertised) if advertised else "none observed"
+        raise DeploymentKitError(
+            "Password-assisted Home Lab bootstrap is unavailable for this trusted target: "
+            f"the SSH server advertises {shown}, not password/keyboard-interactive authentication. "
+            "Use the Strict key-onboarding path and a trusted console or already-authorized session "
+            "for any required server-side key/account-policy change. Do not enable password SSH merely for bootstrap."
+        )
+    return evidence
+
+
 def _install_public_key_with_password(profile: dict[str, Any], *, first_use: bool) -> None:
     info = public_key_info(profile)
     encoded = base64.b64encode(info["publicKey"].encode("utf-8")).decode("ascii")
@@ -316,6 +333,10 @@ def apply_home_lab_bootstrap(
         except DeploymentKitError:
             pass
 
+        # Existing trust lets us discover the server's advertised auth methods safely.
+        # Avoid a guaranteed-to-fail password prompt against public-key-only servers.
+        _require_password_bootstrap_capability(desired)
+
     _install_public_key_with_password(desired, first_use=first_use)
     validate_target_trust_file(desired)
     evidence = verify_access(desired)