@mriekki/project-forge 4.2.0 → 4.3.0

package/assets/components.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "package": "@mriekki/project-forge",
-  "version": "4.2.0",
+  "version": "4.3.0",
   "defaultProfile": "greenfield-project",
   "profiles": {
     "greenfield-project": {
@@ -14,7 +14,7 @@
   "components": {
     "core": {
       "repository": "mriekki/project-forge-core",
-      "commit": "d84829629d151c85bbe4680bc2297abfdf3a3022",
+      "commit": "c35a42d4a87e59b3729797a9a2aace8499a93953",
       "version": "4.0.0",
       "distribution": "greenfield-workspace",
       "descriptor": "assets/core/distribution.json",
@@ -23,7 +23,7 @@
     },
     "deployment": {
       "repository": "mriekki/project-forge-deployment-kit",
-      "commit": "e974c227d9d0768e64605550709db89ccaf93434",
+      "commit": "e5fe3333cad04714d714445866639680378eb23d",
       "distribution": "greenfield-project",
       "descriptor": "assets/deployment/distribution.json",
       "sourceRoot": "assets/generated/deployment",

package/assets/deployment/distribution.json

@@ -31,6 +31,7 @@
     {"source": "src/project_forge_deployment/profile_migration.py", "destination": "tools/project-forge-deployment/project_forge_deployment/profile_migration.py"},
     {"source": "src/project_forge_deployment/profile_repository.py", "destination": "tools/project-forge-deployment/project_forge_deployment/profile_repository.py"},
     {"source": "src/project_forge_deployment/profiles.py", "destination": "tools/project-forge-deployment/project_forge_deployment/profiles.py"},
+    {"source": "src/project_forge_deployment/project_topology.py", "destination": "tools/project-forge-deployment/project_forge_deployment/project_topology.py"},
     {"source": "src/project_forge_deployment/proof_receipt.py", "destination": "tools/project-forge-deployment/project_forge_deployment/proof_receipt.py"},
     {"source": "src/project_forge_deployment/registry_access.py", "destination": "tools/project-forge-deployment/project_forge_deployment/registry_access.py"},
     {"source": "src/project_forge_deployment/registry_cli.py", "destination": "tools/project-forge-deployment/project_forge_deployment/registry_cli.py"},
@@ -45,10 +46,12 @@
     {"source": "src/project_forge_deployment/teardown.py", "destination": "tools/project-forge-deployment/project_forge_deployment/teardown.py"},
     {"source": "src/project_forge_deployment/teardown_cli.py", "destination": "tools/project-forge-deployment/project_forge_deployment/teardown_cli.py"},
     {"source": "src/project_forge_deployment/teardown_remote.py", "destination": "tools/project-forge-deployment/project_forge_deployment/teardown_remote.py"},
+    {"source": "src/project_forge_deployment/topology_cli.py", "destination": "tools/project-forge-deployment/project_forge_deployment/topology_cli.py"},
     {"source": "src/project_forge_deployment/trust.py", "destination": "tools/project-forge-deployment/project_forge_deployment/trust.py"},
     {"source": "docs/DEVELOPER_ENVIRONMENTS.md", "destination": "docs/project-forge/DEVELOPER_ENVIRONMENTS.md"},
     {"source": "docs/WORKSPACE_INSTANCES.md", "destination": "docs/project-forge/WORKSPACE_INSTANCES.md"},
     {"source": "docs/ENVIRONMENT_PROOF.md", "destination": "docs/project-forge/ENVIRONMENT_PROOF.md"},
+    {"source": "docs/PROJECT_TOPOLOGY_BINDING.md", "destination": "docs/project-forge/PROJECT_TOPOLOGY_BINDING.md"},
     {"source": "docs/images/developer-environment-journey.svg", "destination": "docs/project-forge/images/developer-environment-journey.svg"},
     {"source": "docs/images/personal-environment-architecture.svg", "destination": "docs/project-forge/images/personal-environment-architecture.svg"},
     {"source": "docs/images/project-environment-model.svg", "destination": "docs/project-forge/images/project-environment-model.svg"}

package/assets/generated/ASSEMBLY.json

@@ -1,11 +1,11 @@
 {
   "schemaVersion": 1,
   "package": "@mriekki/project-forge",
-  "version": "4.2.0",
+  "version": "4.3.0",
   "components": {
     "core": {
       "repository": "mriekki/project-forge-core",
-      "commit": "d84829629d151c85bbe4680bc2297abfdf3a3022",
+      "commit": "c35a42d4a87e59b3729797a9a2aace8499a93953",
       "version": "4.0.0",
       "distribution": "greenfield-workspace",
       "files": [
@@ -52,7 +52,7 @@
         {
           "source": "core/skills/setup/SKILL.md",
           "destination": ".github/skills/setup/SKILL.md",
-          "sha256": "deb64d0e7ce3a7788e5674182c9788219f2422468ed3e0cc767d49ce569acaea"
+          "sha256": "0ba13a009347742ede2c6e6121a21f29640a05864a994c7a51b4c992c0b2c619"
         },
         {
           "source": "core/skills/build/SKILL.md",
@@ -328,7 +328,7 @@
     },
     "deployment": {
       "repository": "mriekki/project-forge-deployment-kit",
-      "commit": "e974c227d9d0768e64605550709db89ccaf93434",
+      "commit": "e5fe3333cad04714d714445866639680378eb23d",
       "distribution": "greenfield-project",
       "files": [
         {
@@ -394,12 +394,12 @@
         {
           "source": "src/project_forge_deployment/entrypoint.py",
           "destination": "tools/project-forge-deployment/project_forge_deployment/entrypoint.py",
-          "sha256": "94c5eeff4ef684a4665909f7710d95fb4f65c118a71f60782b048697d6a495dd"
+          "sha256": "341e4682a050e9eea8c6ecf0e8728efacc57f06144d9eceb12ac37cf8fb2a3b4"
         },
         {
           "source": "src/project_forge_deployment/environment_cli.py",
           "destination": "tools/project-forge-deployment/project_forge_deployment/environment_cli.py",
-          "sha256": "3c8a0c67c8b75fed7374d1b7b013f95392f84661b6ea182187d07a2b48f206ae"
+          "sha256": "13d41913fd91ad2461bc28e1af0343dd81ba34141c0db8b30f20d89423b64582"
         },
         {
           "source": "src/project_forge_deployment/environment_probe.py",
@@ -471,6 +471,11 @@
           "destination": "tools/project-forge-deployment/project_forge_deployment/profiles.py",
           "sha256": "c8fb1c378af9d39d28f46b300064bec967e2a6f7a13e22d089fc00413c42fd9d"
         },
+        {
+          "source": "src/project_forge_deployment/project_topology.py",
+          "destination": "tools/project-forge-deployment/project_forge_deployment/project_topology.py",
+          "sha256": "72e810d5c6438529195069a5640c74e2774816c16bc6b0f5beff152710240bf7"
+        },
         {
           "source": "src/project_forge_deployment/proof_receipt.py",
           "destination": "tools/project-forge-deployment/project_forge_deployment/proof_receipt.py",
@@ -541,6 +546,11 @@
           "destination": "tools/project-forge-deployment/project_forge_deployment/teardown_remote.py",
           "sha256": "ad764f5a67c43f81b4973dd5639b2c28b23ae883a85e5ae29efc14dad506e88e"
         },
+        {
+          "source": "src/project_forge_deployment/topology_cli.py",
+          "destination": "tools/project-forge-deployment/project_forge_deployment/topology_cli.py",
+          "sha256": "83523efa8c175dfc0235844fcfe3b51a4af3e807e83165cca63c81f675030f8c"
+        },
         {
           "source": "src/project_forge_deployment/trust.py",
           "destination": "tools/project-forge-deployment/project_forge_deployment/trust.py",
@@ -561,6 +571,11 @@
           "destination": "docs/project-forge/ENVIRONMENT_PROOF.md",
           "sha256": "2ce7225ad6166a4ee30f51ea67ec077de0c29ce3a5c39b4ff57bf11cbe25e927"
         },
+        {
+          "source": "docs/PROJECT_TOPOLOGY_BINDING.md",
+          "destination": "docs/project-forge/PROJECT_TOPOLOGY_BINDING.md",
+          "sha256": "50988ac1d797494bcb2d5dd6cece04f6313fb30179ca3132191dea75bcd759cd"
+        },
         {
           "source": "docs/images/developer-environment-journey.svg",
           "destination": "docs/project-forge/images/developer-environment-journey.svg",

package/assets/generated/core/core/skills/setup/SKILL.md

@@ -228,6 +228,26 @@ Normal commands then use that exact name, for example:
 
 Do not create an environment whose required placement/adapter is unsupported; report the concrete `CATALOG GAP` or deferred state instead.
 
+### Complete a deferred remote target binding before remote setup
+
+When the selected existing environment already declares `placement: remote-target` and `adapter: remote-ssh` but has `bindingState: deferred`, treat target selection as a guided Project-configuration subflow rather than a terminal setup blocker.
+
+1. Inspect/sync the developer's reusable non-secret target definitions through installed Deployment Kit personal-profile operations. Prefer `project-forge-deploy environment profile sync --apply --json` when available. Use the returned structured target/import evidence plus current local target profiles; do not invent a workstation registry.
+2. Present compatible existing logical targets as a host-native **single-select** choice. Include `Other / define another target` and `Cancel / keep deferred`. Never silently choose a target, and never preselect or infer a Production target merely from an environment name.
+3. If the developer chooses another target, use the supported Deployment Kit target-profile flow to define that non-secret logical target. Keep SSH identity/trust onboarding separate and never ask for private keys, passwords, or tokens in chat.
+4. Before any Project write, preview the exact binding with the deterministic topology command when available:
+
+```text
+project-forge-deploy topology plan-binding <environment> --target-profile <target> --root . --json
+```
+
+Show the reviewed before/after environment record, selected target, Production classification, changed fields, and required authorization. The supported deferred-binding operation may change only `bindingState` and `targetProfile`; it must not rewrite placement, isolation, exposure, adapter, failure domain, purpose, or role.
+5. Require the bounded Project-configuration authorization reported by the plan. Production-class configuration uses its distinct Production topology-write authorization, but that authorization is **not** a Production proof or application-deployment authorization.
+6. After approval, apply the reviewed plan through the deterministic command (for example `project-forge-deploy topology bind ... --yes --json` when the orchestration layer has just collected the exact required approval). Do not hand-edit `DEPLOYMENT_TOPOLOGY.json` in the skill. If installed Project Forge tooling does not expose the deterministic binding capability, route to the applicable Project Forge update/capability path instead of inventing JSON mutation logic.
+7. Re-read `DEPLOYMENT_TOPOLOGY.json` after the write. Continue normal `/setup <environment>` using the persisted logical target and, when available, use structured `environment setup check`/`plan` evidence for access/platform/proof readiness.
+
+A configured environment that already points at a different target is a **rebind**, not deferred binding completion. Stop for a separate explicit topology-change decision; do not reuse this subflow to move an existing environment silently. Bootstrap remains provenance and must not be rewritten to record the later binding.
+
 ## 7. `/setup remote` and `/setup <environment>` prepare remote-enabled capability
 
 Remote setup proves that this workstation can later work with the configured non-Production or Production-class environment under its normal safety contract. It does **not** publish an artifact or deploy the real application.
@@ -373,4 +393,4 @@ Useful next actions include:
 - `/deploy <environment>` — only after readiness and its own authorization contract;
 - `/tear-down <scope>` — destructive cleanup under its separate gate.
 
-Do not create a second top-level developer-environment-mode workflow. Local/remote workstation convergence belongs here.
+Do not create a second top-level developer-environment-mode workflow. Local/remote workstation convergence belongs here.

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

@@ -0,0 +1,44 @@
+# Project topology target binding
+
+Project Forge keeps reusable non-secret target definitions in the developer's personal profile while each Project owns its logical environment-to-target binding in `DEPLOYMENT_TOPOLOGY.json`.
+
+For an existing environment whose durable intent is already `placement: remote-target`, `adapter: remote-ssh`, and `bindingState: deferred`, Deployment Kit can preview and persist one target binding without rewriting Bootstrap provenance or other topology fields.
+
+## Preview
+
+```text
+project-forge-deploy topology plan-binding <environment> \
+  --target-profile <logical-target> \
+  --root . \
+  --json
+```
+
+The preview:
+
+- reads the current project-owned topology;
+- requires the named environment to already be a remote-target/remote-ssh environment;
+- loads the selected user-scoped target profile;
+- checks declared target OS compatibility;
+- shows the exact before/after environment record;
+- changes only `bindingState` and `targetProfile`;
+- records a topology hash so a later write fails if the file changed after preview;
+- never deploys an application, runs a proof, or changes target SSH/profile state.
+
+A configured environment bound to another target is not eligible for this command. Rebinding requires a separate explicit topology-change contract.
+
+## Apply
+
+```text
+project-forge-deploy topology bind <environment> \
+  --target-profile <logical-target> \
+  --root .
+```
+
+The write requires the bounded phrase reported by the plan:
+
+- `[PROJECT TOPOLOGY WRITE]` for non-Production environments;
+- `[PROJECT PRODUCTION TOPOLOGY WRITE]` for Production-class environments.
+
+Production classification comes from the existing topology role. The command never infers a Production target and this authorization is only for project configuration; it does **not** authorize Production proof or application deployment.
+
+After a successful write, callers should re-read `DEPLOYMENT_TOPOLOGY.json` and continue normal environment setup/readiness from the selected logical target.

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(

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

@@ -0,0 +1,218 @@
+"""Deterministic mutation of project-owned deployment topology bindings."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from copy import deepcopy
+from pathlib import Path
+from typing import Any
+
+from .errors import DeploymentKitError
+from .profiles import load_profile
+
+
+TOPOLOGY_FILE = "DEPLOYMENT_TOPOLOGY.json"
+TOPOLOGY_SCHEMA_VERSION = 1
+PROJECT_TOPOLOGY_WRITE_PHRASE = "[PROJECT TOPOLOGY WRITE]"
+PROJECT_PRODUCTION_TOPOLOGY_WRITE_PHRASE = "[PROJECT PRODUCTION TOPOLOGY WRITE]"
+
+
+def _topology_path(root: str | Path) -> Path:
+    project_root = Path(root).expanduser().resolve()
+    path = project_root / TOPOLOGY_FILE
+    if path.is_symlink() or not path.is_file():
+        raise DeploymentKitError(f"Project deployment topology is missing or unsafe: {path}")
+    return path
+
+
+def _read_topology(root: str | Path) -> tuple[Path, str, dict[str, Any]]:
+    path = _topology_path(root)
+    try:
+        raw = path.read_text(encoding="utf-8")
+        value = json.loads(raw)
+    except (OSError, UnicodeError, json.JSONDecodeError) as error:
+        raise DeploymentKitError(f"Cannot read project deployment topology {path}: {error}") from error
+    if not isinstance(value, dict) or value.get("schemaVersion") != TOPOLOGY_SCHEMA_VERSION:
+        raise DeploymentKitError("Unsupported or malformed project deployment topology schema.")
+    environments = value.get("environments")
+    if not isinstance(environments, list):
+        raise DeploymentKitError("Project deployment topology environments must be an array.")
+    names: list[str] = []
+    for item in environments:
+        if not isinstance(item, dict):
+            raise DeploymentKitError("Project deployment topology contains a non-object environment.")
+        name = item.get("name")
+        if not isinstance(name, str) or not name:
+            raise DeploymentKitError("Project deployment topology contains an environment without a valid name.")
+        names.append(name)
+    if len(names) != len(set(names)):
+        raise DeploymentKitError("Project deployment topology contains duplicate environment names.")
+    return path, raw, value
+
+
+def _environment(value: dict[str, Any], name: str) -> tuple[int, dict[str, Any]]:
+    for index, item in enumerate(value["environments"]):
+        if item.get("name") == name:
+            return index, item
+    raise DeploymentKitError(f"Project deployment topology does not define environment: {name}")
+
+
+def _topology_sha(raw: str) -> str:
+    return hashlib.sha256(raw.encode("utf-8")).hexdigest()
+
+
+def plan_environment_binding(
+    root: str | Path,
+    environment: str,
+    target_profile: str,
+) -> dict[str, Any]:
+    """Preview completion of one deferred remote-target binding without writing project state."""
+
+    path, raw, topology = _read_topology(root)
+    _, current = _environment(topology, environment)
+
+    role = current.get("role")
+    if role not in {"non-production", "production"}:
+        raise DeploymentKitError(f"Environment {environment} has an unsupported role: {role}")
+    if current.get("placement") != "remote-target" or current.get("adapter") != "remote-ssh":
+        raise DeploymentKitError(
+            f"Environment {environment} is not an existing remote-target/remote-ssh binding; "
+            "this command will not rewrite placement or adapter intent."
+        )
+
+    profile = load_profile(target_profile)
+    target_os = profile.get("targetOs")
+    required_os = current.get("targetOs")
+    if required_os not in {None, "other"} and target_os != required_os:
+        raise DeploymentKitError(
+            f"Target profile {target_profile} uses targetOs={target_os}; environment {environment} requires {required_os}."
+        )
+
+    state = current.get("bindingState")
+    existing_target = current.get("targetProfile")
+    production = role == "production"
+    authorization = (
+        PROJECT_PRODUCTION_TOPOLOGY_WRITE_PHRASE
+        if production
+        else PROJECT_TOPOLOGY_WRITE_PHRASE
+    )
+
+    before = deepcopy(current)
+    if state == "configured":
+        if existing_target != target_profile:
+            raise DeploymentKitError(
+                f"Environment {environment} is already configured for target {existing_target}; "
+                "rebinding requires a separate explicit topology-change contract."
+            )
+        return {
+            "status": "already-bound",
+            "projectRoot": str(path.parent),
+            "path": str(path),
+            "environment": environment,
+            "production": production,
+            "targetProfile": target_profile,
+            "targetOs": target_os,
+            "before": before,
+            "after": deepcopy(current),
+            "changedFields": [],
+            "requiredAuthorization": None,
+            "expectedTopologySha256": _topology_sha(raw),
+            "mutated": False,
+        }
+    if state != "deferred":
+        raise DeploymentKitError(
+            f"Environment {environment} has unsupported bindingState={state}; expected deferred or configured."
+        )
+    if existing_target is not None:
+        raise DeploymentKitError(
+            f"Deferred environment {environment} unexpectedly already contains targetProfile={existing_target}."
+        )
+
+    after = deepcopy(current)
+    after["bindingState"] = "configured"
+    after["targetProfile"] = target_profile
+
+    return {
+        "status": "bind",
+        "projectRoot": str(path.parent),
+        "path": str(path),
+        "environment": environment,
+        "production": production,
+        "targetProfile": target_profile,
+        "targetOs": target_os,
+        "targetSummary": {
+            "targetName": profile.get("targetName"),
+            "targetOs": target_os,
+            "hostName": profile.get("hostName"),
+            "sshAlias": profile.get("sshAlias"),
+        },
+        "before": before,
+        "after": after,
+        "changedFields": ["bindingState", "targetProfile"],
+        "requiredAuthorization": authorization,
+        "expectedTopologySha256": _topology_sha(raw),
+        "mutated": False,
+    }
+
+
+def apply_environment_binding(plan: dict[str, Any]) -> dict[str, Any]:
+    """Apply exactly one previously previewed deferred binding, refusing stale topology state."""
+
+    if plan.get("status") == "already-bound":
+        return {
+            "status": "already-bound",
+            "environment": plan.get("environment"),
+            "targetProfile": plan.get("targetProfile"),
+            "production": bool(plan.get("production")),
+            "path": plan.get("path"),
+            "mutated": False,
+        }
+    required = {
+        "projectRoot",
+        "environment",
+        "targetProfile",
+        "before",
+        "after",
+        "expectedTopologySha256",
+        "requiredAuthorization",
+    }
+    if plan.get("status") != "bind" or any(key not in plan for key in required):
+        raise DeploymentKitError("Project topology binding plan is malformed.")
+
+    path, raw, topology = _read_topology(plan["projectRoot"])
+    if _topology_sha(raw) != plan["expectedTopologySha256"]:
+        raise DeploymentKitError(
+            "Project deployment topology changed after preview; re-run the binding plan before writing."
+        )
+    index, current = _environment(topology, plan["environment"])
+    if current != plan["before"]:
+        raise DeploymentKitError(
+            "Selected environment changed after preview; re-run the binding plan before writing."
+        )
+
+    updated = deepcopy(topology)
+    updated["environments"][index] = deepcopy(plan["after"])
+    temp = path.with_name(path.name + ".tmp")
+    if temp.is_symlink():
+        raise DeploymentKitError(f"Refusing to write project topology through a symbolic link: {temp}")
+    try:
+        temp.write_text(json.dumps(updated, indent=2) + "\n", encoding="utf-8")
+        temp.replace(path)
+    except (OSError, UnicodeError) as error:
+        raise DeploymentKitError(f"Cannot persist project deployment topology {path}: {error}") from error
+
+    _, _, reread = _read_topology(plan["projectRoot"])
+    _, bound = _environment(reread, plan["environment"])
+    if bound != plan["after"]:
+        raise DeploymentKitError("Project deployment topology write did not persist the reviewed environment binding.")
+
+    return {
+        "status": "bound",
+        "environment": plan["environment"],
+        "targetProfile": plan["targetProfile"],
+        "production": bool(plan.get("production")),
+        "bindingState": "configured",
+        "path": str(path),
+        "mutated": True,
+    }

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

@@ -0,0 +1,85 @@
+"""CLI for deterministic project-owned deployment topology binding."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+from .errors import DeploymentKitError
+from .project_topology import apply_environment_binding, plan_environment_binding
+
+
+def _print(value: Any, *, as_json: bool) -> 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 args.yes:
+        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 topology")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    for command in ("plan-binding", "bind"):
+        item = sub.add_parser(
+            command,
+            help=(
+                "Preview completion of one deferred remote-target binding"
+                if command == "plan-binding"
+                else "Persist one reviewed deferred remote-target binding"
+            ),
+        )
+        item.add_argument("environment")
+        item.add_argument("--target-profile", required=True)
+        item.add_argument("--root", type=Path, default=Path("."))
+        item.add_argument("--json", action="store_true")
+        if command == "bind":
+            item.add_argument("--yes", action="store_true")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        plan = plan_environment_binding(args.root, args.environment, args.target_profile)
+        if args.command == "plan-binding":
+            _print(plan, as_json=args.json)
+            return 0
+        if plan["status"] == "already-bound":
+            _print(plan, as_json=args.json)
+            return 0
+        if not args.json:
+            _print(plan, as_json=False)
+        _confirm(
+            args,
+            plan["requiredAuthorization"],
+            f"bind project environment {args.environment} to target profile {args.target_profile}",
+        )
+        result = apply_environment_binding(plan)
+        _print(result, as_json=args.json)
+        return 0
+    except DeploymentKitError as error:
+        print(f"ERROR: {error}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/package.json

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