@mriekki/project-forge 3.0.0 → 4.1.0

package/assets/generated/deployment/docs/DEVELOPER_ENVIRONMENTS.md

@@ -2,7 +2,7 @@
 
 Status: **CORE WORKSTATION/TARGET MECHANICS IMPLEMENTED; AUTOMATED HOST PACKAGE PREPARATION REMAINS INCREMENTAL**
 
-This document is the canonical developer-environment model for Project Forges. It describes the developer-facing progression from a generated repository to local development, optional Staging/Production capability, additional workstations, and additional remote boxes.
+This document is the canonical developer-environment model for Project Forge. It describes the developer-facing progression from a generated repository to local development, optional Staging/Production capability, additional workstations, and additional remote boxes.
 
 The happy path intentionally hides Bootstrap/package/control-plane plumbing. Developers should see meaningful milestones and actionable setup, while the underlying repositories retain exact provenance and safety evidence.
 
@@ -44,6 +44,37 @@ The normal conversational entry point is:
 
 The first local success target is `LOCAL WORKSPACE READY`. Remote access must not block it unless the Project explicitly requires a remote dependency for local development.
 
+For remote onboarding, conversational `/setup remote` or `/setup <environment>` should consume one deterministic read-only setup state machine rather than manually reconstructing low-level steps:
+
+```text
+project-forge-deploy environment setup status <target> --json
+project-forge-deploy environment setup plan <target> --json
+```
+
+When target access and the host platform are ready, proof context can be included without performing a write:
+
+```text
+project-forge-deploy environment setup plan <target> \
+  --owner-repo <owner/repo> \
+  --environment <logical-environment> \
+  --json
+```
+
+Add `--production` only when that logical environment is Production-class. Setup status/plan never authorizes a write; they report the existing authorization phrase and exact next deterministic operation when a write is required.
+
+Readiness is deliberately separated into:
+
+```text
+WORKSPACE READY
+TARGET DEFINITION READY
+TARGET ACCESS READY
+HOST PLATFORM READY
+DEPLOYMENT PATH PROVEN
+APPLICATION DEPLOYED
+```
+
+The last state is not part of setup. A successful disposable proof does not deploy the Project application.
+
 ## Progress and next action
 
 Use `/progress` to answer what is complete, what is blocked/deferred, who owns the next action, and local/Staging/Production capability state.
@@ -101,6 +132,8 @@ An empty profile with `targets: []` is valid. A local-only developer never needs
 
 `profile sync` fetches and validates the GitHub profile, updates the validated local cache, and with `--apply` creates only missing non-conflicting local target definitions. Existing differing local definitions are never overwritten.
 
+Portable identity deliberately excludes workstation-local `addressOverride`, identity-file, and trust-file state. A separately verified temporary IP therefore does not make the same portable host definition a different target.
+
 `profile publish` merges new non-conflicting local target definitions into the private profile and fails on conflicts rather than silently replacing remote definitions.
 
 ### Workstation-local state
@@ -116,6 +149,8 @@ Each workstation owns its own:
 
 Private SSH keys are never synchronized between computers. A Mark Windows key, Mark Mac key, Kyle Mac key, and Daniel Windows key are distinct identities even when they can reach the same remote server.
 
+The deterministic doctor resolves and reports the actual SSH executable selected from the workstation environment; all Deployment Kit SSH operations use that resolved toolchain rather than asking the developer to mix shell-specific SSH clients manually.
+
 ## Home Lab remote onboarding
 
 The implemented Home Lab path is password-assisted bootstrap followed by normal strict key-only operation.
@@ -164,7 +199,7 @@ The first Project on a computer may install/verify required local tools and Dock
 
 ### Remote Ubuntu target
 
-Target access can now be established from the local workstation, but full automatic Ubuntu package preparation is still an incremental capability. The desired host progression remains:
+Target access can be established from the local workstation, but full automatic Ubuntu package preparation is still an incremental capability. The desired host progression remains:
 
 ```text
 Ubuntu/sudo verification
@@ -175,7 +210,7 @@ Ubuntu/sudo verification
 → TARGET READY
 ```
 
-The current platform doctor/install contract still requires host prerequisites to exist before shared-platform installation. Until a reviewed host-package bootstrap is added, `/setup remote` must report missing host packages as an actionable preparation gap rather than pretending they were installed.
+The current platform doctor/install contract still requires host prerequisites to exist before shared-platform installation. Until a reviewed host-package bootstrap is added, `/setup remote` reports missing host packages as an actionable preparation gap rather than pretending they were installed. The deterministic setup plan keeps this as a distinct `HOST PLATFORM READY` blocker.
 
 Healthy existing Docker/Project Forge installations are adopted/verified, not recreated. Ambiguous/incompatible existing state fails closed rather than being overwritten.
 
@@ -188,13 +223,16 @@ The implemented workstation-mediated artifact path is:
 ```text
 local GitHub/GHCR authentication when needed
 → acquire/build exact immutable image locally
-→ verify exact identity/digest
+→ preserve registry RepoDigest as declared/release identity
+→ resolve local Docker config/image ID
 → stream Docker image over verified SSH
 → remote docker load
-→ verify exact image remotely
-→ deploy/health-check using the preloaded image
+→ verify the same config/image ID remotely
+→ deploy/health-check by that verified loaded image ID
 ```
 
+Docker `save`/`load` does not guarantee that a registry RepoDigest remains inspectable as a remote RepoDigest after load. Project Forge therefore uses two explicit identities: registry digest for reviewed release provenance, and Docker config/image ID for transport verification and the preloaded runtime reference.
+
 Remote Home Lab boxes therefore do not need a developer's persistent GitHub PAT for the normal workstation-mediated deployment path.
 
 Application deployment selects this with:
@@ -203,7 +241,7 @@ Application deployment selects this with:
 --image-source workstation
 ```
 
-The legacy `--image-source remote-registry` path remains available during migration/for explicit target-side registry use.
+The legacy `--image-source remote-registry` path remains available for explicit target-side registry use.
 
 A credential needed to acquire a private image is entered only through the local Docker/GitHub credential boundary. Never paste it into chat or put it on a command line.
 
@@ -275,7 +313,7 @@ When GitHub cannot be reached, profile sync can use the validated last-known-goo
 
 ## Migration for existing developers
 
-Existing Mark/Kyle environments should migrate fully to this model rather than remain permanently dual-mode.
+Existing developer environments should migrate fully to this model rather than remain permanently dual-mode.
 
 The migration contract is:
 
@@ -284,8 +322,8 @@ inventory existing workstation/targets
 → ensure private personal project-forge-profile + validated cache
 → adopt healthy existing Docker/SSH/trust where valid
 → establish workstation-mediated artifact delivery
-→ prove Staging end-to-end
-→ verify Production access/readiness without deploying
+→ prove a non-Production environment end-to-end
+→ verify Production access/readiness without deploying when Production is configured
 → remove/archive superseded legacy configuration only after verification
 ```
 
@@ -325,11 +363,13 @@ The intended small human surface is:
 
 ```text
 /setup
+/setup local
+/setup remote
+/setup <environment>
 /progress
 /next-step
-/developer-env-mode status|local|remote
 /deployment-readiness <environment>
 /deploy <environment>
 ```
 
-The first three are the normal guided experience. `project-forge-deploy environment ...` commands are deterministic implementation/fallback surfaces and can be invoked directly when desired.
+`/setup` is the single setup front door; the local/remote/environment forms select its scope rather than introducing a separate developer-environment command. `project-forge-deploy environment ...` commands are deterministic implementation/fallback surfaces and can be invoked directly when desired.

package/assets/generated/deployment/docs/ENVIRONMENT_PROOF.md

@@ -13,15 +13,24 @@ this workstation
 → verified target/profile access
 → ready shared host platform
 → pull small stable probe image locally
-→ resolve exact immutable RepoDigest
-→ transfer exact image over verified SSH
-→ deploy with the managed application runtime
+→ resolve exact immutable registry RepoDigest
+→ resolve local Docker config/image ID
+→ transfer image over verified SSH
+→ verify the same config/image ID after remote docker load
+→ deploy with the managed application runtime using that verified loaded image ID
 → verify HTTP health
 → tear down the reserved probe runtime
-→ verify cleanup evidence
+→ verify cleanup and image-cache evidence
 ```
 
-The current default probe image tag is `nginx:alpine`. The tag is never treated as the deployed identity: Project Forge pulls it locally and resolves an exact `@sha256:` RepoDigest before image transfer or remote runtime mutation.
+The current default probe image tag is `nginx:alpine`. The mutable tag is never treated as deployed identity.
+
+Project Forge deliberately records two exact identities because Docker `save`/`load` does not guarantee that a registry RepoDigest remains inspectable under the same repository reference after load:
+
+- **registry digest** — immutable reviewed artifact/release identity (`repository@sha256:...`);
+- **Docker config/image ID** — content identity used to verify the workstation-to-target transfer and to run the preloaded image (`sha256:...`).
+
+The registry digest remains in the deployment spec and release/proof evidence. The loaded runtime is verified and launched by the matching Docker config/image ID. A target that already has that exact image ID can reuse it without retransferring the image.
 
 The probe uses:
 
@@ -33,6 +42,20 @@ The probe uses:
 - the existing per-app/per-environment deployment lock;
 - automatic cleanup through the existing scoped tear-down machinery.
 
+## Setup orchestration
+
+Before running proof commands directly, the read-only remote setup orchestrator can show whether target access and the host platform are actually ready:
+
+```text
+project-forge-deploy environment setup status <target> --json
+project-forge-deploy environment setup plan <target> \
+  --owner-repo <owner/repo> \
+  --environment <name> \
+  --json
+```
+
+These commands never perform the proof or authorize a write. They make `TARGET ACCESS READY`, `HOST PLATFORM READY`, and `DEPLOYMENT PATH PROVEN` separate states.
+
 ## Commands
 
 Read-only plan:
@@ -78,17 +101,44 @@ Production-class proof:
 
 A successful proof never authorizes the later real application deployment. Production proof never authorizes a Production application deployment.
 
+## Terminal evidence
+
+A proof run returns a terminal result even when the operational path fails after the run begins. The result distinguishes planning from observed execution and includes, when available:
+
+```text
+preflight
+registryDigest
+localImageId
+transferState
+remoteImageId
+runtimeState
+httpHealth
+cleanupState
+imageCacheState
+proof
+mutated
+finalMutationState
+error
+cleanupError
+```
+
+A read-only plan does not claim `mutated: false` as though it were the eventual run result. The run reports whether transfer/runtime mutation actually occurred and whether cleanup completed.
+
+A failed proof exits nonzero even when structured terminal evidence was produced successfully.
+
 ## Cleanup
 
 The proof attempts cleanup even when deployment raises after mutation begins.
 
 Successful completion requires terminal cleanup evidence (`removed` or already `absent`) for the reserved probe runtime. If deployment succeeds but cleanup cannot be verified, the command fails rather than reporting a clean proof.
 
+A loaded Docker image may remain cached after runtime cleanup. That state is reported explicitly (for example `runtime-clean-image-cached`) rather than being presented as an unmodified host. Cached image content is not application runtime or persistent application data.
+
 The probe must not delete another Project, another application, another logical environment, or shared host platform state.
 
 ## Relationship to `/setup` and `/deploy`
 
-`/setup` may run this proof after the developer selects a named remote environment to prepare on the current workstation.
+`/setup remote` or `/setup <environment>` may use deterministic setup status/plan first, then run this proof after the developer selects the named remote environment and the relevant write authorization is granted.
 
 A later first real `/deploy <environment>` can reuse fresh proof evidence for target access/platform/transport mechanics and ask only unresolved application-specific questions such as persistence, health, route/exposure, and immutable application artifact policy.
 

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

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import re
 import subprocess
 from typing import Any
 
@@ -19,48 +20,42 @@ from .profiles import load_profile
 from .ssh import ssh_args, verify_access
 
 
-def _preloaded_script(spec: dict[str, Any]) -> str:
+_IMAGE_ID_RE = re.compile(r"^sha256:[0-9a-f]{64}$")
+
+
+def _runtime_image_id(value: str) -> str:
+    if not isinstance(value, str) or _IMAGE_ID_RE.fullmatch(value) is None:
+        raise DeploymentKitError("Preloaded runtime image ID must be sha256:<64 lowercase hex>.")
+    return value
+
+
+def _preloaded_script(spec: dict[str, Any], runtime_image_id: str) -> str:
+    runtime_image = _runtime_image_id(runtime_image_id)
     script = build_remote_script(spec)
     registry_block = "    decode_desired\n    configure_registry_auth\n"
     if registry_block not in script:
         raise DeploymentKitError("Application runtime template no longer contains the expected registry-auth hook.")
     script = script.replace(registry_block, "    decode_desired\n", 1)
+
     pull = '    docker pull "$D_IMAGE" >/dev/null\n'
-    replacement = '''    if ! docker image inspect "$D_IMAGE" >/dev/null 2>&1; then
-        echo "Exact application image was not preloaded by the workstation-mediated deployment path." >&2
-        exit 40
-    fi
-'''
+    replacement = (
+        f'    if ! docker image inspect "{runtime_image}" >/dev/null 2>&1; then\n'
+        '        echo "Exact application image ID was not preloaded by the workstation-mediated deployment path." >&2\n'
+        "        exit 40\n"
+        "    fi\n"
+    )
     if pull not in script:
         raise DeploymentKitError("Application runtime template no longer contains the expected image-pull hook.")
-    return script.replace(pull, replacement, 1)
-
+    script = script.replace(pull, replacement, 1)
 
-def _run_preloaded_deploy(
-    profile: dict[str, Any],
-    address: str,
-    spec: dict[str, Any],
-    expected_spec_sha: str,
-) -> None:
-    command = ssh_args(
-        profile,
-        address,
-        command="sudo -n bash -s -- deploy " + (expected_spec_sha or "NONE") + " " + profile["user"],
-    )
-    completed = subprocess.run(
-        command,
-        input=_preloaded_script(spec).encode("utf-8"),
-        check=False,
-        capture_output=True,
-    )
-    if completed.returncode != 0:
-        stdout = completed.stdout.decode("utf-8", errors="replace")
-        stderr = completed.stderr.decode("utf-8", errors="replace")
-        detail = stderr.strip() or stdout.strip() or f"exit {completed.returncode}"
-        raise DeploymentKitError(f"Workstation-mediated remote application deployment failed: {detail}")
+    runtime_hook = '    docker_args+=("$D_IMAGE")\n'
+    if runtime_hook not in script:
+        raise DeploymentKitError("Application runtime template no longer contains the expected runtime-image hook.")
+    script = script.replace(runtime_hook, f'    docker_args+=("{runtime_image}")\n', 1)
+    return script
 
 
-def apply_app_deploy_from_workstation(plan: dict[str, Any]) -> dict[str, Any]:
+def _validate_plan(plan: dict[str, Any]) -> None:
     required = {
         "targetName",
         "action",
@@ -87,19 +82,67 @@ def apply_app_deploy_from_workstation(plan: dict[str, Any]) -> dict[str, Any]:
     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.")
 
-    transfer_image(plan["targetName"], plan["image"])
+def _validate_transfer(plan: dict[str, Any], transfer: dict[str, Any]) -> str:
+    required = {
+        "targetName",
+        "image",
+        "registryDigest",
+        "localImageId",
+        "remoteImageId",
+        "runtimeImage",
+        "status",
+        "mutated",
+    }
+    if not isinstance(transfer, dict) or set(transfer) != required:
+        raise DeploymentKitError("Malformed workstation image-transfer evidence.")
+    if transfer["targetName"] != plan["targetName"]:
+        raise DeploymentKitError("Image-transfer target does not match the deployment plan.")
+    if transfer["registryDigest"] != plan["image"] or transfer["image"] != plan["image"]:
+        raise DeploymentKitError("Image-transfer registry digest does not match the deployment plan.")
+    local_id = _runtime_image_id(transfer["localImageId"])
+    remote_id = _runtime_image_id(transfer["remoteImageId"])
+    runtime_id = _runtime_image_id(transfer["runtimeImage"])
+    if not (local_id == remote_id == runtime_id):
+        raise DeploymentKitError("Workstation and remote Docker image IDs do not match.")
+    if transfer["status"] not in {"already-present", "transferred"} or not isinstance(transfer["mutated"], bool):
+        raise DeploymentKitError("Image-transfer evidence has an invalid terminal state.")
+    return runtime_id
+
+
+def _run_preloaded_deploy(
+    profile: dict[str, Any],
+    address: str,
+    spec: dict[str, Any],
+    expected_spec_sha: str,
+    runtime_image_id: str,
+) -> None:
+    command = ssh_args(
+        profile,
+        address,
+        command="sudo -n bash -s -- deploy " + (expected_spec_sha or "NONE") + " " + profile["user"],
+    )
+    completed = subprocess.run(
+        command,
+        input=_preloaded_script(spec, runtime_image_id).encode("utf-8"),
+        check=False,
+        capture_output=True,
+    )
+    if completed.returncode != 0:
+        stdout = completed.stdout.decode("utf-8", errors="replace")
+        stderr = completed.stderr.decode("utf-8", errors="replace")
+        detail = stderr.strip() or stdout.strip() or f"exit {completed.returncode}"
+        raise DeploymentKitError(f"Workstation-mediated remote application deployment failed: {detail}")
+
+
+def apply_app_deploy_with_preloaded_image(
+    plan: dict[str, Any], transfer: dict[str, Any]
+) -> dict[str, Any]:
+    """Apply a reviewed deployment plan using already-verified transfer evidence."""
+
+    _validate_plan(plan)
+    runtime_image_id = _validate_transfer(plan, transfer)
 
-    # Image transfer can take time. Re-check the material app/platform evidence before
-    # changing runtime state; a changed plan must never ride through on stale approval.
     current = app_inventory(plan["targetName"])
     if _inventory_snapshot(current) != plan["inventorySnapshot"]:
         raise DeploymentKitError(
@@ -116,6 +159,7 @@ def apply_app_deploy_from_workstation(plan: dict[str, Any]) -> dict[str, Any]:
         evidence["address"],
         plan["spec"],
         plan["expectedSpecSha256"] or "",
+        runtime_image_id,
     )
 
     final = app_inventory(plan["targetName"])
@@ -132,5 +176,22 @@ def apply_app_deploy_from_workstation(plan: dict[str, Any]) -> dict[str, Any]:
         raise DeploymentKitError("Application deployment completed but runtime readiness is not healthy.")
     final["mutated"] = True
     final["imageSource"] = "workstation-transfer"
+    final["imageTransfer"] = transfer
     final["attachesSharedNetwork"] = NETWORK_NAME
     return final
+
+
+def apply_app_deploy_from_workstation(plan: dict[str, Any]) -> dict[str, Any]:
+    _validate_plan(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.")
+
+    transfer = transfer_image(plan["targetName"], plan["image"])
+    return apply_app_deploy_with_preloaded_image(plan, transfer)

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

@@ -1,4 +1,4 @@
-"""CLI for portable developer environment definitions and Home Lab onboarding."""
+"""CLI for portable developer environment definitions and remote setup orchestration."""
 
 from __future__ import annotations
 
@@ -15,6 +15,7 @@ from .environment_probe import (
     plan_environment_proof,
     run_environment_proof,
 )
+from .environment_setup import remote_setup_plan, remote_setup_status
 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
@@ -59,6 +60,25 @@ def build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(prog="project-forge-deploy environment")
     groups = parser.add_subparsers(dest="group", required=True)
 
+    setup = groups.add_parser(
+        "setup",
+        help="Read-only remote setup status/plan orchestration across target access, host platform, and proof readiness",
+    )
+    setup_sub = setup.add_subparsers(dest="command", required=True)
+    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_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")
+    setup_plan.add_argument("--environment")
+    setup_plan.add_argument(
+        "--production",
+        action="store_true",
+        help="Classify the optional proof environment as Production",
+    )
+    setup_plan.add_argument("--json", action="store_true")
+
     profile = groups.add_parser("profile", help="Personal/portable non-secret target profile operations")
     profile_sub = profile.add_subparsers(dest="command", required=True)
 
@@ -178,6 +198,20 @@ def _home_lab_plan(args: argparse.Namespace) -> dict[str, Any]:
 def main(argv: list[str] | None = None) -> int:
     args = build_parser().parse_args(argv)
     try:
+        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 == "plan":
+            _print(
+                remote_setup_plan(
+                    args.name,
+                    owner_repo=args.owner_repo,
+                    environment=args.environment,
+                    production=args.production,
+                ),
+                as_json=args.json,
+            )
+            return 0
         if args.group == "profile" and args.command == "status":
             _print(repository_status(), as_json=args.json)
             return 0
@@ -243,16 +277,19 @@ def main(argv: list[str] | None = None) -> int:
                 production=args.production,
                 probe_image=args.probe_image,
             )
-            _print(plan, as_json=args.json if args.command == "plan" else False)
             if args.command == "plan":
+                _print(plan, as_json=args.json)
                 return 0
+            if not args.json:
+                _print(plan, as_json=False)
             _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
+            result = run_environment_proof(plan)
+            _print(result, as_json=args.json)
+            return 0 if result.get("proof") == "passed" else 2
         raise DeploymentKitError("Unsupported environment command.")
     except DeploymentKitError as error:
         print(f"ERROR: {error}", file=sys.stderr)