@mriekki/project-forge 4.2.0 → 4.4.0

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

@@ -0,0 +1,194 @@
+"""Isolation-aware application deployment orchestration.
+
+The low-level application runtime owns immutable container mechanics. This module
+binds those mechanics to the broader read-only environment isolation contract so
+real application deployment plans cannot ignore route, persistence, or sibling
+ownership changes that occur after human review.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Iterable
+
+from .app_runtime import apply_app_deploy as _apply_runtime_deploy
+from .app_runtime import plan_app_deploy as _plan_runtime_deploy
+from .app_runtime_workstation import apply_app_deploy_with_preloaded_image
+from .environment_isolation import environment_isolation_preflight
+from .errors import DeploymentKitError
+from .image_transfer import transfer_image
+
+
+ISOLATION_REVIEW_KEY = "isolationReview"
+
+
+def app_isolation_check(
+    target_name: str,
+    *,
+    owner_repo: str,
+    environment: str,
+    production: bool = False,
+    app_slug: str,
+    container_name: str,
+    runtime_port: int,
+    persistence_mode: str,
+    database_file: str | None = None,
+    route_hostnames: Iterable[str] | None = None,
+) -> dict[str, Any]:
+    """Return read-only isolation evidence for a real application footprint."""
+
+    return environment_isolation_preflight(
+        target_name,
+        owner_repo=owner_repo,
+        environment=environment,
+        production=production,
+        app_slug=app_slug,
+        container_name=container_name,
+        runtime_port=runtime_port,
+        persistence_mode=persistence_mode,
+        database_file=database_file,
+        route_hostnames=route_hostnames,
+        require_vacant_app_identity=False,
+    )
+
+
+def _check_from_spec(
+    target_name: str,
+    spec: dict[str, Any],
+    *,
+    production: bool,
+    database_file: str | None,
+    route_hostnames: Iterable[str] | None,
+) -> dict[str, Any]:
+    return app_isolation_check(
+        target_name,
+        owner_repo=spec["ownerRepo"],
+        environment=spec["environment"],
+        production=production,
+        app_slug=spec["appSlug"],
+        container_name=spec["containerName"],
+        runtime_port=spec["runtimePort"],
+        persistence_mode=spec["persistence"]["mode"],
+        database_file=database_file,
+        route_hostnames=route_hostnames,
+    )
+
+
+def _require_clear(isolation: dict[str, Any], *, context: str) -> None:
+    if isolation.get("state") == "clear":
+        return
+    conflicts = isolation.get("conflicts") or []
+    codes = sorted(
+        {
+            item.get("code", "unknown-collision")
+            for item in conflicts
+            if isinstance(item, dict)
+        }
+    )
+    detail = ", ".join(codes) if codes else "unspecified collision"
+    raise DeploymentKitError(
+        f"Application isolation {context} is blocked: {detail}. Resolve the collision before deployment."
+    )
+
+
+def _review(isolation: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "schemaVersion": isolation["schemaVersion"],
+        "targetName": isolation["targetName"],
+        "ownerRepo": isolation["ownerRepo"],
+        "environment": isolation["environment"],
+        "production": isolation["production"],
+        "state": isolation["state"],
+        "sharedFailureDomain": isolation["sharedFailureDomain"],
+        "siblingEnvironments": isolation["siblingEnvironments"],
+        "desired": isolation["desired"],
+        "checks": isolation["checks"],
+        "conflicts": isolation["conflicts"],
+        "inventorySnapshots": isolation["inventorySnapshots"],
+        "evidenceSha256": isolation["evidenceSha256"],
+    }
+
+
+def _runtime_plan(plan: dict[str, Any]) -> dict[str, Any]:
+    if not isinstance(plan, dict) or ISOLATION_REVIEW_KEY not in plan:
+        raise DeploymentKitError("Application deployment plan is missing reviewed isolation evidence.")
+    return {key: value for key, value in plan.items() if key != ISOLATION_REVIEW_KEY}
+
+
+def plan_app_deploy(
+    target_name: str,
+    spec: dict[str, Any],
+    *,
+    production: bool = False,
+    database_file: str | None = None,
+    route_hostnames: Iterable[str] | None = None,
+) -> dict[str, Any]:
+    """Plan a real application deployment with current isolation evidence."""
+
+    runtime_plan = _plan_runtime_deploy(target_name, spec)
+    isolation = _check_from_spec(
+        target_name,
+        spec,
+        production=production,
+        database_file=database_file,
+        route_hostnames=route_hostnames,
+    )
+    _require_clear(isolation, context="preflight")
+
+    plan = dict(runtime_plan)
+    plan[ISOLATION_REVIEW_KEY] = _review(isolation)
+    return plan
+
+
+def revalidate_app_isolation(plan: dict[str, Any]) -> dict[str, Any]:
+    """Recheck the reviewed application footprint immediately before mutation."""
+
+    runtime_plan = _runtime_plan(plan)
+    review = plan[ISOLATION_REVIEW_KEY]
+    if not isinstance(review, dict):
+        raise DeploymentKitError("Application deployment plan has malformed isolation evidence.")
+    desired = review.get("desired")
+    if not isinstance(desired, dict):
+        raise DeploymentKitError("Application deployment plan has malformed isolation desired state.")
+
+    current = _check_from_spec(
+        runtime_plan["targetName"],
+        runtime_plan["spec"],
+        production=bool(review.get("production")),
+        database_file=desired.get("databaseFile"),
+        route_hostnames=desired.get("routeHostnames") or [],
+    )
+    _require_clear(current, context="recheck")
+
+    reviewed_sha = review.get("evidenceSha256")
+    if not isinstance(reviewed_sha, str) or current["evidenceSha256"] != reviewed_sha:
+        raise DeploymentKitError(
+            "Application isolation state changed after the plan was reviewed; create and authorize a fresh plan."
+        )
+    return current
+
+
+def apply_app_deploy(plan: dict[str, Any]) -> dict[str, Any]:
+    """Apply a registry-backed runtime plan after isolation revalidation."""
+
+    revalidate_app_isolation(plan)
+    return _apply_runtime_deploy(_runtime_plan(plan))
+
+
+def apply_app_deploy_from_workstation(plan: dict[str, Any]) -> dict[str, Any]:
+    """Transfer an exact image, then recheck isolation again before runtime mutation."""
+
+    revalidate_app_isolation(plan)
+    runtime_plan = _runtime_plan(plan)
+    transfer = transfer_image(runtime_plan["targetName"], runtime_plan["image"])
+    revalidate_app_isolation(plan)
+    return apply_app_deploy_with_preloaded_image(runtime_plan, transfer)
+
+
+__all__ = [
+    "ISOLATION_REVIEW_KEY",
+    "app_isolation_check",
+    "apply_app_deploy",
+    "apply_app_deploy_from_workstation",
+    "plan_app_deploy",
+    "revalidate_app_isolation",
+]

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

@@ -11,6 +11,7 @@ from .local_cli import main as local_main
 from .registry_cli import main as registry_main
 from .sqlite_cli import main as sqlite_main
 from .teardown_cli import main as teardown_main
+from .topology_cli import main as topology_main
 
 
 def main(argv: list[str] | None = None) -> int:
@@ -27,6 +28,8 @@ def main(argv: list[str] | None = None) -> int:
         return sqlite_main(args[1:])
     if args and args[0] == "tear-down":
         return teardown_main(args[1:])
+    if args and args[0] == "topology":
+        return topology_main(args[1:])
     if not args or args == ["--help"] or args == ["-h"]:
         print("Command group: app  Remote immutable application runtime inventory/deployment")
         print("Command group: environment  Portable profiles, Home Lab onboarding, and image transfer")
@@ -34,4 +37,5 @@ def main(argv: list[str] | None = None) -> int:
         print("Command group: registry  Read-only exact-image registry access verification")
         print("Command group: sqlite  SQLite persistence import/backup/migration/rollback checks")
         print("Command group: tear-down  Scoped destructive Project environment/local cleanup")
+        print("Command group: topology  Project-owned logical environment binding")
     return core_main(args)

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

@@ -56,6 +56,32 @@ def _confirm(args: argparse.Namespace, phrase: str, action: str) -> None:
         raise DeploymentKitError(f"{action.capitalize()} was not authorized.")
 
 
+def _setup_readiness(result: dict[str, Any], *, require_deployment_path: bool) -> dict[str, Any]:
+    required_phases = ["workspace", "targetDefinition", "targetAccess", "hostPlatform"]
+    expected_states = {
+        "workspace": "ready",
+        "targetDefinition": "ready",
+        "targetAccess": "ready",
+        "hostPlatform": "ready",
+    }
+    if require_deployment_path:
+        required_phases.append("deploymentPath")
+        expected_states["deploymentPath"] = "proven"
+
+    not_ready = [
+        phase
+        for phase in required_phases
+        if result["phases"][phase]["state"] != expected_states[phase]
+    ]
+    return {
+        "ready": not not_ready,
+        "requiredThrough": "deploymentPath" if require_deployment_path else "hostPlatform",
+        "requiredPhases": required_phases,
+        "notReadyPhases": not_ready,
+        "applicationRequired": False,
+    }
+
+
 def build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(prog="project-forge-deploy environment")
     groups = parser.add_subparsers(dest="group", required=True)
@@ -68,6 +94,19 @@ def build_parser() -> argparse.ArgumentParser:
     setup_status = setup_sub.add_parser("status", help="Show one terminal readiness model for a remote target")
     setup_status.add_argument("name")
     setup_status.add_argument("--json", action="store_true")
+    setup_check = setup_sub.add_parser(
+        "check",
+        help="Return success only when the requested remote setup readiness contract is satisfied",
+    )
+    setup_check.add_argument("name")
+    setup_check.add_argument("--owner-repo")
+    setup_check.add_argument("--environment")
+    setup_check.add_argument(
+        "--production",
+        action="store_true",
+        help="Require proof evidence classified as Production; requires owner/environment proof context",
+    )
+    setup_check.add_argument("--json", action="store_true")
     setup_plan = setup_sub.add_parser("plan", help="Show the exact next deterministic remote setup action")
     setup_plan.add_argument("name")
     setup_plan.add_argument("--owner-repo")
@@ -201,6 +240,23 @@ def main(argv: list[str] | None = None) -> int:
         if args.group == "setup" and args.command == "status":
             _print(remote_setup_status(args.name), as_json=args.json)
             return 0
+        if args.group == "setup" and args.command == "check":
+            if args.production and (args.owner_repo is None or args.environment is None):
+                raise DeploymentKitError(
+                    "--production requires --owner-repo and --environment for setup readiness checking."
+                )
+            result = remote_setup_plan(
+                args.name,
+                owner_repo=args.owner_repo,
+                environment=args.environment,
+                production=args.production,
+            )
+            readiness = _setup_readiness(
+                result,
+                require_deployment_path=args.owner_repo is not None,
+            )
+            _print({**result, "readinessCheck": readiness}, as_json=args.json)
+            return 0 if readiness["ready"] else 2
         if args.group == "setup" and args.command == "plan":
             _print(
                 remote_setup_plan(
@@ -279,7 +335,10 @@ def main(argv: list[str] | None = None) -> int:
             )
             if args.command == "plan":
                 _print(plan, as_json=args.json)
-                return 0
+                return 0 if plan.get("runnable", True) else 2
+            if not plan.get("runnable", True):
+                _print(plan, as_json=args.json)
+                return 2
             if not args.json:
                 _print(plan, as_json=False)
             _confirm(