merge(milestone): v1.29 Reposplit + Identity Layer Bring-Live to main (release v1.28.6)

---ci---
project: acdl
phase: 6
milestone: v1.29
status: complete
---/ci---

core/lambda/nova_idp_setup.py

@@ -2,6 +2,15 @@
 
 Backing logic for ``nova idp setup``. The CLI (``nova/idp/setup.py``)
 is a thin ≤50-line delegate to this module (CAP-034).
+
+From v1.29 (REQ-369, spec §7.5) the active provisioning path is
+``terraform apply`` in the ``nova-platform-ops`` checkout. The CFN
+template generated here is archived as read-only reference in
+``docs/archive/nova-idp-cfn-v1.28.md``; :func:`generate_and_deploy`
+(the former CFN deploy path) emits a ``DeprecationWarning`` and is
+retained only as a fallback when terraform is absent from PATH.
+:func:`terraform_apply` and :func:`terraform_plan` are the new
+preferred paths.
 """
 
 from __future__ import annotations
@@ -9,13 +18,21 @@ from __future__ import annotations
 import importlib.util
 import json
 import os
+import shutil
 import subprocess
 import sys
 import tempfile
+import warnings
 from pathlib import Path
 from typing import Any
 
 
+_CFN_ARCHIVE_REF = (
+    "CFN path is archived; install terraform or use nova-platform-ops. "
+    "See docs/archive/nova-idp-cfn-v1.28.md."
+)
+
+
 def _load_cfn():
     """Load core/lambda/nova_idp_cfn.py via importlib (`lambda` is reserved)."""
     p = Path(__file__).parent / "nova_idp_cfn.py"
@@ -71,6 +88,13 @@ def generate_and_deploy(
 ) -> dict[str, Any]:
     """Generate the CFN template + deploy (REQ-341, NFR-10 y/N approval).
 
+    .. deprecated:: v1.29
+        The active path is :func:`terraform_apply` (REQ-369, spec §7.5).
+        This CFN deploy path is archived as read-only reference in
+        ``docs/archive/nova-idp-cfn-v1.28.md`` and retained only as a
+        fallback when terraform is absent from PATH. It emits a
+        ``DeprecationWarning`` on every non-dry-run invocation.
+
     Args:
         public_jwks_domain: optional custom JWKS domain.
         dry_run: if True, print the resource summary only (no deploy).
@@ -84,6 +108,7 @@ def generate_and_deploy(
     summary = resource_summary(template)
     if dry_run:
         return {"template": template, "summary": summary, "deployed": False}
+    warnings.warn(_CFN_ARCHIVE_REF, DeprecationWarning, stacklevel=2)
     # NFR-10: explicit y/N approval before cloudformation deploy.
     print("Resource summary:")
     for rtype, count in sorted(summary.items()):
@@ -123,6 +148,43 @@ def generate_and_deploy(
     return {"template": template, "summary": summary, "deployed": deployed}
 
 
+def terraform_apply(*, auto_approve: bool = True) -> dict[str, Any]:
+    """Delegate provisioning to ``terraform apply`` (REQ-369, spec §7.5).
+
+    The operator runs this from the ``nova-platform-ops`` checkout root
+    (where the Terraform modules live). This function shells out to
+    ``terraform`` on PATH; the caller (``nova/idp/setup.py``) is
+    responsible for the ``shutil.which("terraform")`` gate.
+
+    Args:
+        auto_approve: pass ``-auto-approve`` (default True; the y/N gate
+            is the operator's PR review in nova-platform-ops).
+
+    Returns:
+        ``{"deployed": bool, "returncode": int, "command": [str]}``.
+    """
+    cmd = ["terraform", "apply"]
+    if auto_approve:
+        cmd.append("-auto-approve")
+    proc = subprocess.run(cmd)
+    return {"deployed": proc.returncode == 0, "returncode": proc.returncode, "command": cmd}
+
+
+def terraform_plan() -> dict[str, Any]:
+    """Delegate verification to ``terraform plan`` (REQ-369, spec §7.5).
+
+    Reports the diff between the live stack and the Terraform source in
+    the ``nova-platform-ops`` checkout. The caller is responsible for
+    the ``shutil.which("terraform")`` gate.
+
+    Returns:
+        ``{"passed": bool, "returncode": int, "command": [str]}``.
+    """
+    cmd = ["terraform", "plan"]
+    proc = subprocess.run(cmd)
+    return {"passed": proc.returncode == 0, "returncode": proc.returncode, "command": cmd}
+
+
 def verify() -> dict[str, Any]:
     """Run the KMS round-trip verification (REQ-340 --verify).