@mriekki/project-forge 0.0.0-stage → 2.0.0

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

@@ -0,0 +1,271 @@
+"""CLI for portable developer environment definitions and Home Lab onboarding."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+from .environment_probe import (
+    DEFAULT_PROBE_IMAGE,
+    ENVIRONMENT_PROOF_WRITE_PHRASE,
+    PRODUCTION_ENVIRONMENT_PROOF_WRITE_PHRASE,
+    plan_environment_proof,
+    run_environment_proof,
+)
+from .errors import DeploymentKitError
+from .home_lab import HOME_LAB_BOOTSTRAP_PHRASE, apply_home_lab_bootstrap, plan_home_lab_bootstrap
+from .image_transfer import transfer_image, verify_local_image
+from .portable_profile import apply_import, export_bundle, load_bundle, plan_import, write_bundle
+from .profile_migration import PERSONAL_PROFILE_MIGRATION_PHRASE, migrate_current_workstation
+from .profile_repository import (
+    PERSONAL_PROFILE_WRITE_PHRASE,
+    ensure_profile_repository,
+    publish_profile,
+    repository_status,
+    sync_profile,
+)
+
+
+LOCAL_PROFILE_IMPORT_PHRASE = "[LOCAL PROFILE IMPORT]"
+REMOTE_IMAGE_TRANSFER_PHRASE = "[REMOTE IMAGE TRANSFER]"
+
+
+def _print(value: Any, *, as_json: bool = False) -> None:
+    if as_json:
+        print(json.dumps(value, indent=2, sort_keys=True))
+        return
+    if isinstance(value, dict):
+        for key, item in value.items():
+            if isinstance(item, (dict, list)):
+                print(f"{key}: {json.dumps(item, sort_keys=True)}")
+            else:
+                print(f"{key}: {item}")
+        return
+    print(value)
+
+
+def _confirm(args: argparse.Namespace, phrase: str, action: str) -> None:
+    if getattr(args, "yes", False):
+        return
+    entered = input(f"Type {phrase} to {action}: ").strip()
+    if entered != phrase:
+        raise DeploymentKitError(f"{action.capitalize()} was not authorized.")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="project-forge-deploy environment")
+    groups = parser.add_subparsers(dest="group", required=True)
+
+    profile = groups.add_parser("profile", help="Personal/portable non-secret target profile operations")
+    profile_sub = profile.add_subparsers(dest="command", required=True)
+
+    status = profile_sub.add_parser("status", help="Inspect the authenticated developer's private project-forge-profile repository")
+    status.add_argument("--json", action="store_true")
+
+    ensure = profile_sub.add_parser(
+        "ensure",
+        help="Create/initialize the authenticated developer's private project-forge-profile repository when missing",
+    )
+    ensure.add_argument("--json", action="store_true")
+    ensure.add_argument("--yes", action="store_true")
+
+    migrate = profile_sub.add_parser(
+        "migrate",
+        help="One-time adoption of this workstation's existing target definitions into the personal profile model",
+    )
+    migrate.add_argument("--json", action="store_true")
+    migrate.add_argument("--yes", action="store_true")
+
+    sync = profile_sub.add_parser(
+        "sync",
+        help="Fetch/validate the personal profile, update last-known-good cache, and optionally import missing definitions",
+    )
+    sync.add_argument("--apply", action="store_true", help="Create only missing non-conflicting local target profiles")
+    sync.add_argument("--json", action="store_true")
+
+    publish = profile_sub.add_parser(
+        "publish",
+        help="Merge new non-conflicting local target definitions into the private personal profile",
+    )
+    publish.add_argument("--json", action="store_true")
+    publish.add_argument("--yes", action="store_true")
+
+    export = profile_sub.add_parser("export", help="Export sanitized target definitions to a portable bundle")
+    export.add_argument("--target", action="append", default=[])
+    export.add_argument("--output", type=Path, required=True)
+    export.add_argument("--json", action="store_true")
+
+    preview = profile_sub.add_parser("preview-import", help="Preview a portable bundle without writing local profiles")
+    preview.add_argument("bundle", type=Path)
+    preview.add_argument("--json", action="store_true")
+
+    apply = profile_sub.add_parser("import", help="Import only non-conflicting portable target definitions")
+    apply.add_argument("bundle", type=Path)
+    apply.add_argument("--json", action="store_true")
+    apply.add_argument("--yes", action="store_true")
+
+    home_lab = groups.add_parser(
+        "home-lab",
+        help="Password-assisted one-time SSH bootstrap followed by strict per-workstation key access",
+    )
+    home_lab_sub = home_lab.add_subparsers(dest="command", required=True)
+    for command in ("plan", "bootstrap"):
+        sub = home_lab_sub.add_parser(command)
+        sub.add_argument("name")
+        sub.add_argument("--host-name", required=True)
+        sub.add_argument("--user", required=True)
+        sub.add_argument("--port", type=int, default=22)
+        sub.add_argument("--ssh-alias")
+        sub.add_argument("--address", help="Optional exact temporary IP; stable host identity remains --host-name/alias")
+        sub.add_argument(
+            "--protect-key-with-passphrase",
+            action="store_true",
+            help="Let ssh-keygen prompt locally for a key passphrase; default Home Lab key is unencrypted",
+        )
+        sub.add_argument("--json", action="store_true")
+        if command == "bootstrap":
+            sub.add_argument("--yes", action="store_true")
+
+    image = groups.add_parser("image", help="Workstation-mediated exact Docker image transfer")
+    image_sub = image.add_subparsers(dest="command", required=True)
+    image_check = image_sub.add_parser("check", help="Verify an exact immutable image exists locally")
+    image_check.add_argument("--image", required=True)
+    image_check.add_argument("--json", action="store_true")
+    image_transfer = image_sub.add_parser("transfer", help="Stream an exact local image to a verified target over SSH")
+    image_transfer.add_argument("name")
+    image_transfer.add_argument("--image", required=True)
+    image_transfer.add_argument("--json", action="store_true")
+    image_transfer.add_argument("--yes", action="store_true")
+
+    proof = groups.add_parser(
+        "proof",
+        help="Plan/run a disposable end-to-end deployment proof for one named remote environment",
+    )
+    proof_sub = proof.add_subparsers(dest="command", required=True)
+    for command in ("plan", "run"):
+        sub = proof_sub.add_parser(command)
+        sub.add_argument("name", help="Logical target profile name")
+        sub.add_argument("--owner-repo", required=True)
+        sub.add_argument("--environment", required=True)
+        sub.add_argument(
+            "--production",
+            action="store_true",
+            help="Classify the named environment as Production even when its name is not literally 'production'",
+        )
+        sub.add_argument("--probe-image", default=DEFAULT_PROBE_IMAGE)
+        sub.add_argument("--json", action="store_true")
+        if command == "run":
+            sub.add_argument("--yes", action="store_true")
+
+    return parser
+
+
+def _home_lab_plan(args: argparse.Namespace) -> dict[str, Any]:
+    return plan_home_lab_bootstrap(
+        args.name,
+        host_name=args.host_name,
+        user=args.user,
+        port=args.port,
+        ssh_alias=args.ssh_alias,
+        address=args.address,
+        protect_key_with_passphrase=args.protect_key_with_passphrase,
+    )
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        if args.group == "profile" and args.command == "status":
+            _print(repository_status(), as_json=args.json)
+            return 0
+        if args.group == "profile" and args.command == "ensure":
+            _print(repository_status(), as_json=False)
+            _confirm(args, PERSONAL_PROFILE_WRITE_PHRASE, "create/initialize the private personal Project Forge profile when needed")
+            _print(ensure_profile_repository(), as_json=args.json)
+            return 0
+        if args.group == "profile" and args.command == "migrate":
+            _confirm(args, PERSONAL_PROFILE_MIGRATION_PHRASE, "migrate this workstation to the personal Project Forge profile model")
+            _print(migrate_current_workstation(), as_json=args.json)
+            return 0
+        if args.group == "profile" and args.command == "sync":
+            _print(sync_profile(apply=args.apply), as_json=args.json)
+            return 0
+        if args.group == "profile" and args.command == "publish":
+            _confirm(args, PERSONAL_PROFILE_WRITE_PHRASE, "publish non-secret target definitions to the private personal Project Forge profile")
+            _print(publish_profile(), as_json=args.json)
+            return 0
+        if args.group == "profile" and args.command == "export":
+            bundle = export_bundle(args.target or None)
+            path = write_bundle(bundle, args.output)
+            _print({"path": str(path), "targets": [item["targetName"] for item in bundle["targets"]]}, as_json=args.json)
+            return 0
+        if args.group == "profile" and args.command == "preview-import":
+            _print(plan_import(load_bundle(args.bundle)), as_json=args.json)
+            return 0
+        if args.group == "profile" and args.command == "import":
+            plan = plan_import(load_bundle(args.bundle))
+            _print(plan, as_json=False)
+            if plan["hasConflicts"]:
+                raise DeploymentKitError("Import conflicts must be resolved explicitly; no local profiles were changed.")
+            _confirm(args, LOCAL_PROFILE_IMPORT_PHRASE, "import these portable target definitions")
+            _print(apply_import(plan), as_json=args.json)
+            return 0
+        if args.group == "home-lab":
+            plan = _home_lab_plan(args)
+            _print(plan, as_json=args.json if args.command == "plan" else False)
+            if args.command == "plan":
+                return 0
+            _confirm(args, HOME_LAB_BOOTSTRAP_PHRASE, f"bootstrap Home Lab access for target {args.name}")
+            _print(
+                apply_home_lab_bootstrap(
+                    plan,
+                    protect_key_with_passphrase=args.protect_key_with_passphrase,
+                ),
+                as_json=args.json,
+            )
+            return 0
+        if args.group == "image" and args.command == "check":
+            _print(verify_local_image(args.image), as_json=args.json)
+            return 0
+        if args.group == "image" and args.command == "transfer":
+            _print(verify_local_image(args.image), as_json=False)
+            _confirm(args, REMOTE_IMAGE_TRANSFER_PHRASE, f"transfer this exact image to target {args.name}")
+            _print(transfer_image(args.name, args.image), as_json=args.json)
+            return 0
+        if args.group == "proof":
+            plan = plan_environment_proof(
+                args.name,
+                owner_repo=args.owner_repo,
+                environment=args.environment,
+                production=args.production,
+                probe_image=args.probe_image,
+            )
+            _print(plan, as_json=args.json if args.command == "plan" else False)
+            if args.command == "plan":
+                return 0
+            _confirm(
+                args,
+                plan["requiredAuthorization"],
+                f"run a disposable deployment proof for {plan['environment']} on target {plan['targetName']}",
+            )
+            _print(run_environment_proof(plan), as_json=args.json)
+            return 0
+        raise DeploymentKitError("Unsupported environment command.")
+    except DeploymentKitError as error:
+        print(f"ERROR: {error}", file=sys.stderr)
+        return 2
+
+
+__all__ = [
+    "ENVIRONMENT_PROOF_WRITE_PHRASE",
+    "PRODUCTION_ENVIRONMENT_PROOF_WRITE_PHRASE",
+    "build_parser",
+    "main",
+]
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -0,0 +1,228 @@
+"""Disposable end-to-end proof for one named remote deployment environment."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+import shutil
+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 .box_platform import platform_status
+from .errors import DeploymentKitError
+from .registry_access import normalize_registry_image
+from .teardown import tear_down_poc
+
+ENVIRONMENT_PROOF_WRITE_PHRASE = "[ENVIRONMENT PROOF WRITE]"
+PRODUCTION_ENVIRONMENT_PROOF_WRITE_PHRASE = "[PRODUCTION ENVIRONMENT PROOF]"
+DEFAULT_PROBE_IMAGE = "nginx:alpine"
+
+_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_.-]+$")
+
+
+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 _docker() -> str:
+    path = shutil.which("docker")
+    if path is None:
+        raise DeploymentKitError("Docker CLI is unavailable on the workstation.")
+    return path
+
+
+def _probe_slug(owner_repo: str) -> str:
+    digest = hashlib.sha256(owner_repo.encode("utf-8")).hexdigest()[:10]
+    return f"project-forge-env-probe-{digest}"
+
+
+def _resolve_probe_image(image_tag: str) -> str:
+    if not isinstance(image_tag, str) or not image_tag.strip() or "@sha256:" in image_tag:
+        raise DeploymentKitError("probeImage must be a non-empty mutable image tag; Project Forge resolves it to an exact digest.")
+    docker = _docker()
+    pulled = subprocess.run(
+        [docker, "pull", image_tag],
+        check=False,
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+    )
+    if pulled.returncode != 0:
+        raise DeploymentKitError(
+            "Environment proof image pull failed: " + (pulled.stderr or pulled.stdout).strip()
+        )
+    inspected = subprocess.run(
+        [docker, "image", "inspect", "--format", "{{json .RepoDigests}}", image_tag],
+        check=False,
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+    )
+    if inspected.returncode != 0:
+        raise DeploymentKitError(
+            "Environment proof image digest inspection failed: " + (inspected.stderr or inspected.stdout).strip()
+        )
+    try:
+        digests = json.loads(inspected.stdout.strip())
+    except json.JSONDecodeError as error:
+        raise DeploymentKitError("Environment proof image inspection returned malformed RepoDigests JSON.") from error
+    if not isinstance(digests, list):
+        raise DeploymentKitError("Environment proof image inspection did not return a RepoDigests list.")
+    for item in digests:
+        try:
+            return normalize_registry_image(item)
+        except DeploymentKitError:
+            continue
+    raise DeploymentKitError("Environment proof image has no usable immutable sha256 RepoDigest.")
+
+
+def plan_environment_proof(
+    target_name: str,
+    *,
+    owner_repo: str,
+    environment: str,
+    production: bool = False,
+    probe_image: str = DEFAULT_PROBE_IMAGE,
+) -> dict[str, Any]:
+    owner = _owner_repo(owner_repo)
+    env = _slug(environment, "environment")
+    if not isinstance(production, bool):
+        raise DeploymentKitError("production must be true or false.")
+    if not isinstance(probe_image, str) or not probe_image.strip():
+        raise DeploymentKitError("probeImage must be a non-empty image tag.")
+    platform = platform_status(target_name)
+    if platform.get("state") != "ready":
+        raise DeploymentKitError(
+            f"Environment proof requires a ready shared platform; target '{target_name}' is '{platform.get('state', 'unknown')}'."
+        )
+    return {
+        "targetName": target_name,
+        "ownerRepo": owner,
+        "environment": env,
+        "production": production,
+        "probeAppSlug": _probe_slug(owner),
+        "probeImageTag": probe_image,
+        "artifactDelivery": "workstation-transfer",
+        "persistence": "none",
+        "healthPath": "/",
+        "cleanup": "automatic",
+        "requiredAuthorization": (
+            PRODUCTION_ENVIRONMENT_PROOF_WRITE_PHRASE if production else ENVIRONMENT_PROOF_WRITE_PHRASE
+        ),
+        "mutated": False,
+    }
+
+
+def run_environment_proof(plan: dict[str, Any]) -> dict[str, Any]:
+    required = {
+        "targetName",
+        "ownerRepo",
+        "environment",
+        "production",
+        "probeAppSlug",
+        "probeImageTag",
+        "artifactDelivery",
+        "persistence",
+        "healthPath",
+        "cleanup",
+        "requiredAuthorization",
+        "mutated",
+    }
+    if not isinstance(plan, dict) or set(plan) != required or plan["mutated"] is not False:
+        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)
+
+    deployment: dict[str, Any] | None = None
+    cleanup: dict[str, Any] | None = None
+    deploy_error: Exception | None = None
+    cleanup_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
+    finally:
+        try:
+            cleanup = tear_down_poc(
+                {
+                    "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.")
+
+    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,
+    }

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

@@ -0,0 +1,5 @@
+"""Deployment Kit exception types."""
+
+
+class DeploymentKitError(Exception):
+    """Expected fail-closed operational or configuration error."""