agentcore-cli 0.31.1__py3-none-any.whl

agentcore/cdk/toolkit.py

@@ -0,0 +1,706 @@
+"""CDK toolkit driver (port of upstream ``src/cli/cdk/toolkit-lib``).
+
+Upstream drives ``@aws-cdk/toolkit-lib`` in-process. The Python port keeps the vended TypeScript
+CDK app and shells out to the CDK CLI the project already depends on
+(``agentcore/cdk/node_modules/.bin/cdk``, falling back to ``npx cdk``):
+
+=====================================  ==========================================================
+toolkit-lib call (upstream)            cdk CLI invocation (here)
+=====================================  ==========================================================
+``fromCdkApp('node dist/bin/cdk.js')``  ``--app "node dist/bin/cdk.js"`` with ``cwd`` = project dir
+``synth(source, {validateStacks})``    ``cdk synth --app ... --output cdk.out --quiet --validation``
+``fromAssemblyDirectory(dir)``         ``--app <assembly dir>`` for every later operation
+``deploy(src, {stacks})``              ``cdk deploy <patterns> --require-approval never --ci``
+``diff(src, {stacks})``                ``cdk diff <patterns>``
+``destroy(src, {stacks})``             ``cdk destroy <patterns> --force``
+``list(src, {stacks})``                ``cdk list <patterns>``
+``bootstrap(envs, {parameters})``      ``cdk bootstrap <envs> --bootstrap-customer-key`` (or
+                                       ``--bootstrap-kms-key-id <id>``)
+=====================================  ==========================================================
+
+The region override is forwarded through the child environment (``AWS_REGION`` /
+``AWS_DEFAULT_REGION``) exactly as upstream does for the app subprocess; a profile goes through
+``AWS_PROFILE``. Context comes from the project's ``cdk.json`` (the CLI reads it from ``cwd``),
+just as toolkit-lib reads it for ``fromCdkApp``. No hotswap: deploys are full change-set deploys,
+which is toolkit-lib's default.
+
+Progress: toolkit-lib streams stack activity through its IoHost (``CDK_TOOLKIT_I5501..I5901``).
+Here, while ``cdk deploy`` runs, CloudFormation stack events are polled with boto3 and turned into
+the same message codes, so the IoHost contract (``SwitchableIoHost``) is unchanged.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import threading
+import time
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any, Protocol
+
+from agentcore.cdk.constants import CDK_APP_ENTRY, CDK_PROJECT_DIR
+from agentcore.cli.errors import is_changeset_in_progress_error
+from agentcore.cloudformation.stack_events import StackEventPoller, describe_failures, format_stack_event
+from agentcore.lib.constants import CONFIG_DIR
+from agentcore.lib.utils.platform import is_windows
+from agentcore.lib.utils.subprocess import SubprocessResult, run_subprocess_capture
+
+# Command used to execute the CDK app (matches "app" in cdk.json; requires `tsc` build first).
+CDK_APP_COMMAND = "node"
+
+# Default assembly output directory (relative to the CDK project directory).
+CDK_OUT_DIR = "cdk.out"
+
+# toolkit-lib message codes relevant for deploy progress display.
+DEPLOY_MESSAGE_CODES = frozenset(
+    {
+        "CDK_TOOLKIT_I5501",  # Stack monitoring start
+        "CDK_TOOLKIT_I5502",  # Stack activity event (resource events with progress)
+        "CDK_TOOLKIT_I5503",  # Stack monitoring end
+        "CDK_TOOLKIT_I5900",  # Deployment results
+        "CDK_TOOLKIT_I5901",  # Deployment success
+    }
+)
+
+# Retry policy for transient changeset conflicts (identical to upstream).
+DEPLOY_MAX_RETRIES = 3
+DEPLOY_BASE_DELAY_S = 5.0
+
+
+class StackSelectionStrategy:
+    """String constants mirroring toolkit-lib's ``StackSelectionStrategy`` enum."""
+
+    ALL_STACKS = "all-stacks"
+    MAIN_ASSEMBLY = "main-assembly"
+    ONLY_SINGLE = "only-single"
+    PATTERN_MATCH = "pattern-match"
+    PATTERN_MUST_MATCH = "pattern-must-match"
+    PATTERN_MUST_MATCH_SINGLE = "pattern-must-match-single"
+
+
+@dataclass(frozen=True)
+class StackSelector:
+    strategy: str = StackSelectionStrategy.PATTERN_MUST_MATCH
+    patterns: tuple[str, ...] = ()
+
+
+def pattern_must_match(*patterns: str) -> StackSelector:
+    return StackSelector(StackSelectionStrategy.PATTERN_MUST_MATCH, tuple(patterns))
+
+
+# ---------------------------------------------------------------------------
+# IoHost (port of toolkit-lib/types.ts)
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class IoMessage:
+    code: str
+    message: str
+    level: str = "info"
+    time: datetime = field(default_factory=lambda: datetime.now(UTC))
+    action: str | None = None
+    data: Any = None
+
+
+class IoHost(Protocol):
+    def notify(self, msg: IoMessage) -> None: ...
+
+
+class _SilentIoHost:
+    """Suppresses all CDK output."""
+
+    def notify(self, msg: IoMessage) -> None:
+        return None
+
+
+silent_io_host: IoHost = _SilentIoHost()
+
+
+@dataclass
+class ResourceProgress:
+    completed: int
+    total: int
+
+
+@dataclass
+class DeployMessage:
+    """CDK message filtered for deploy progress display (data pre-extracted)."""
+
+    code: str
+    message: str
+    level: str
+    timestamp: datetime
+    progress: ResourceProgress | None = None
+    outputs: dict[str, str] | None = None
+    stack_arn: str | None = None
+
+
+_PROGRESS_RE = re.compile(r"\|\s*(\d+)/(\d+)\s*\|")
+
+
+def extract_progress_from_message(message: str) -> ResourceProgress | None:
+    """I5502 lines look like ``StackName | X/Y | timestamp | STATUS | ...``."""
+    match = _PROGRESS_RE.search(message)
+    return ResourceProgress(int(match.group(1)), int(match.group(2))) if match else None
+
+
+RawMessageCallback = Callable[[str, str, str, Any], None]
+
+
+@dataclass
+class SwitchableIoHost:
+    """IoHost that starts silent; ``set_verbose(True)`` enables message capture."""
+
+    verbose: bool = False
+    on_message: Callable[[DeployMessage], None] | None = None
+    on_raw_message: RawMessageCallback | None = None
+
+    @property
+    def io_host(self) -> IoHost:
+        return self
+
+    def set_verbose(self, verbose: bool) -> None:
+        self.verbose = verbose
+
+    def set_on_message(self, callback: Callable[[DeployMessage], None] | None) -> None:
+        self.on_message = callback
+
+    def set_on_raw_message(self, callback: RawMessageCallback | None) -> None:
+        self.on_raw_message = callback
+
+    def notify(self, msg: IoMessage) -> None:
+        if not self.verbose:
+            return
+        code = msg.code or "UNKNOWN"
+        text = msg.message if isinstance(msg.message, str) else ""
+        if self.on_raw_message:
+            self.on_raw_message(code, msg.level or "info", text, msg.data)
+        if self.on_message and msg.code in DEPLOY_MESSAGE_CODES:
+            deploy_message = DeployMessage(
+                code=msg.code,
+                message=text,
+                level=msg.level or "info",
+                timestamp=msg.time,
+                progress=extract_progress_from_message(text),
+            )
+            if msg.code == "CDK_TOOLKIT_I5900" and isinstance(msg.data, Mapping):
+                if msg.data.get("outputs"):
+                    deploy_message.outputs = dict(msg.data["outputs"])
+                if msg.data.get("stackArn"):
+                    deploy_message.stack_arn = msg.data["stackArn"]
+            self.on_message(deploy_message)
+
+
+def create_switchable_io_host() -> SwitchableIoHost:
+    return SwitchableIoHost()
+
+
+# ---------------------------------------------------------------------------
+# Driver
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class SynthOutput:
+    stack_names: list[str]
+    assembly_directory: str
+
+
+class CdkCommandError(RuntimeError):
+    """A cdk subprocess failed. The message carries the CLI's own error text for classification."""
+
+    def __init__(self, message: str, result: SubprocessResult | None = None):
+        super().__init__(message)
+        self.result = result
+
+
+def _with_error_context(context: str, err: BaseException) -> BaseException:
+    """Prefix the error message with ``CDK <context> failed:`` (upstream mutates ``err.message``)."""
+    message = f"CDK {context} failed: {err}"
+    if isinstance(err, CdkCommandError):
+        return CdkCommandError(message, err.result)
+    wrapped = RuntimeError(message)
+    wrapped.__cause__ = err
+    return wrapped
+
+
+_ANSI_RE = re.compile(r"\x1b\[[0-9;]*[a-zA-Z]")
+
+
+def _strip_ansi(text: str) -> str:
+    return _ANSI_RE.sub("", text)
+
+
+def _failure_text(result: SubprocessResult) -> str:
+    """The meaningful part of a failed cdk run's output."""
+    text = _strip_ansi((result.stderr or "").strip() or (result.stdout or "").strip())
+    if not text:
+        reason = f"code {result.code}" if result.code is not None else f"signal {result.signal}"
+        return f"cdk exited with {reason}"
+    # Prefer the CLI's explicit error lines ("❌ ...", "Error: ...") when present.
+    lines = [line for line in text.splitlines() if line.strip()]
+    errorish = [line for line in lines if line.lstrip().startswith(("❌", "Error", "error"))]
+    if errorish:
+        tail = lines[lines.index(errorish[0]) :]
+        return "\n".join(tail[-40:])
+    return "\n".join(lines[-40:])
+
+
+def resolve_cdk_command(project_dir: str | os.PathLike[str]) -> tuple[str, list[str]]:
+    """The project's own CDK CLI (``node_modules/.bin/cdk``), else ``npx cdk``."""
+    bin_dir = Path(project_dir) / "node_modules" / ".bin"
+    candidates = ["cdk.cmd", "cdk"] if is_windows else ["cdk"]
+    for name in candidates:
+        path = bin_dir / name
+        if path.exists():
+            return str(path), []
+    return "npx", ["cdk"]
+
+
+Runner = Callable[..., SubprocessResult]
+
+
+class CdkToolkitWrapper:
+    """Thin driver around the CDK CLI, pre-configured for the vended AgentCore CDK project."""
+
+    def __init__(
+        self,
+        project_dir: str | os.PathLike[str] | None = None,
+        *,
+        io_host: IoHost | None = None,
+        profile: str | None = None,
+        region: str | None = None,
+        runner: Runner | None = None,
+        poll_interval: float = 2.0,
+        sleep: Callable[[float], None] = time.sleep,
+    ) -> None:
+        self.project_dir = str(project_dir or Path(os.getcwd()) / CONFIG_DIR / CDK_PROJECT_DIR)
+        self.io_host: IoHost = io_host or silent_io_host
+        self.profile = profile
+        self.region = region
+        self._runner = runner
+        self.poll_interval = poll_interval
+        self._sleep = sleep
+        self._command: tuple[str, list[str]] | None = None
+        self._env: dict[str, str] | None = None
+        self._assembly_dir: str | None = None
+        self._stack_names: list[str] = []
+
+    # -- setup -------------------------------------------------------------------------------
+
+    def get_project_dir(self) -> str:
+        return self.project_dir
+
+    def get_cdk_app_command(self) -> str:
+        return f"{CDK_APP_COMMAND} {CDK_APP_ENTRY}"
+
+    def initialize(self) -> None:
+        """Resolve the CDK CLI and the child environment. Must be called before any operation."""
+        try:
+            profile = self.profile or os.environ.get("AWS_PROFILE")
+            region = self.region or os.environ.get("AWS_REGION") or os.environ.get("AWS_DEFAULT_REGION")
+            env = dict(os.environ)
+            if region:
+                env["AWS_REGION"] = region
+                env["AWS_DEFAULT_REGION"] = region
+            if profile:
+                env["AWS_PROFILE"] = profile
+            # The CLI is driven programmatically: no update notices, no interactive prompts.
+            env.setdefault("CDK_DISABLE_VERSION_CHECK", "1")
+            self._env = env
+            self._command = resolve_cdk_command(self.project_dir)
+        except Exception as exc:  # pragma: no cover - defensive, mirrors withErrorContext
+            raise _with_error_context(f"initialize (project: {self.project_dir})", exc) from exc
+
+    def _ensure_initialized(self) -> tuple[tuple[str, list[str]], dict[str, str]]:
+        if self._command is None or self._env is None:
+            raise RuntimeError("CdkToolkitWrapper not initialized. Call initialize() first.")
+        return self._command, self._env
+
+    def _run(self, args: Sequence[str]) -> SubprocessResult:
+        (command, prefix), env = self._ensure_initialized()
+        runner = self._runner or run_subprocess_capture
+        return runner(command, [*prefix, *args], cwd=self.project_dir, env=env)
+
+    def _app_args(self) -> list[str]:
+        """``--app`` for an operation: the synthesized assembly if any (no re-synth), else the app."""
+        return ["--app", self._assembly_dir or self.get_cdk_app_command()]
+
+    @staticmethod
+    def _selection_args(stacks: StackSelector | None) -> list[str]:
+        if stacks is None or stacks.strategy == StackSelectionStrategy.ALL_STACKS:
+            return ["--all"]
+        if stacks.patterns:
+            return list(stacks.patterns)
+        return ["--all"] if stacks.strategy == StackSelectionStrategy.MAIN_ASSEMBLY else []
+
+    def _notify(self, code: str, message: str, level: str = "info", data: Any = None, action: str | None = None):
+        self.io_host.notify(IoMessage(code=code, message=message, level=level, data=data, action=action))
+
+    def _forward_output(self, result: SubprocessResult, action: str) -> None:
+        """Pass the CLI's own output lines to the IoHost (visible only to verbose/raw listeners)."""
+        for stream, level in ((result.stdout, "info"), (result.stderr, "info")):
+            for line in (stream or "").splitlines():
+                if line.strip():
+                    self._notify("CDK_TOOLKIT_I0000", _strip_ansi(line), level, action=action)
+
+    # -- synth -------------------------------------------------------------------------------
+
+    def synth(self) -> SynthOutput:
+        """Synthesize the app; later deploy/diff/destroy reuse the produced assembly."""
+        self._ensure_initialized()
+        self.dispose_synth_result()
+        out_dir = str(Path(self.project_dir) / CDK_OUT_DIR)
+        result = self._run(
+            [
+                "synth",
+                "--app",
+                self.get_cdk_app_command(),
+                "--output",
+                out_dir,
+                "--quiet",
+                "--validation",
+                "--no-notices",
+            ]
+        )
+        self._forward_output(result, "synth")
+        if result.code != 0:
+            raise _with_error_context("synth", CdkCommandError(_failure_text(result), result))
+        self._assembly_dir = out_dir
+        self._stack_names = read_assembly_stack_names(out_dir)
+        return SynthOutput(stack_names=list(self._stack_names), assembly_directory=out_dir)
+
+    def dispose_synth_result(self) -> None:
+        self._assembly_dir = None
+        self._stack_names = []
+
+    def dispose(self) -> None:
+        """Release state. The CLI holds no locks once it exits, so there is nothing else to free."""
+        self.dispose_synth_result()
+        self._command = None
+        self._env = None
+
+    # -- deploy ------------------------------------------------------------------------------
+
+    def deploy(self, stacks: StackSelector | None = None) -> None:
+        """Deploy, retrying transient changeset conflicts (5s, 10s backoff, 3 attempts)."""
+        self._ensure_initialized()
+        last_error: BaseException | None = None
+        for attempt in range(DEPLOY_MAX_RETRIES):
+            try:
+                self._deploy_once(stacks)
+                return
+            except Exception as exc:
+                last_error = _with_error_context("deploy", exc)
+                if is_changeset_in_progress_error(last_error) and attempt < DEPLOY_MAX_RETRIES - 1:
+                    delay = DEPLOY_BASE_DELAY_S * (2**attempt)
+                    self._notify(
+                        "CDK_TOOLKIT_W0001",
+                        f"Changeset operation in progress, retrying in {delay:g}s "
+                        f"(attempt {attempt + 1}/{DEPLOY_MAX_RETRIES})...",
+                        level="warn",
+                        action="deploy",
+                    )
+                    self._sleep(delay)
+                    continue
+                raise last_error from exc
+        raise last_error or RuntimeError("Deploy failed after retries")  # pragma: no cover
+
+    def _deploy_once(self, stacks: StackSelector | None) -> None:
+        outputs_file = str(Path(self._assembly_dir or Path(self.project_dir) / CDK_OUT_DIR) / "agentcore-outputs.json")
+        args = [
+            "deploy",
+            *self._selection_args(stacks),
+            *self._app_args(),
+            "--require-approval",
+            "never",
+            "--ci",
+            "--progress",
+            "events",
+            "--no-notices",
+            "--outputs-file",
+            outputs_file,
+        ]
+        stack_names = self._target_stack_names(stacks)
+        region = (self._env or {}).get("AWS_REGION")
+        pollers = [StackEventPoller(region=region, stack_name=name) for name in stack_names] if region else []
+        totals = {name: self._template_resource_count(name) for name in stack_names}
+        completed: dict[str, set[str]] = {name: set() for name in stack_names}
+
+        holder: dict[str, Any] = {}
+
+        def run() -> None:
+            try:
+                holder["result"] = self._run(args)
+            except BaseException as exc:  # noqa: BLE001 - re-raised on the calling thread
+                holder["error"] = exc
+
+        started = False
+        thread = threading.Thread(target=run, name="cdk-deploy", daemon=True)
+        thread.start()
+
+        def drain() -> None:
+            nonlocal started
+            for poller in pollers:
+                for event in poller.poll():
+                    if not started:
+                        started = True
+                        self._notify("CDK_TOOLKIT_I5501", f"Deploying {poller.stack_name}", action="deploy")
+                    logical = event.get("LogicalResourceId") or ""
+                    status = event.get("ResourceStatus") or ""
+                    if logical != poller.stack_name and status.endswith("_COMPLETE"):
+                        completed[poller.stack_name].add(logical)
+                    total = max(totals.get(poller.stack_name, 0), len(completed[poller.stack_name]))
+                    line = format_stack_event(poller.stack_name, event, len(completed[poller.stack_name]), total)
+                    level = "error" if status.endswith("FAILED") else "info"
+                    self._notify("CDK_TOOLKIT_I5502", line, level, data=event, action="deploy")
+
+        while thread.is_alive():
+            thread.join(self.poll_interval)
+            drain()
+        drain()
+
+        if "error" in holder:
+            raise holder["error"]
+        result: SubprocessResult = holder["result"]
+        self._forward_output(result, "deploy")
+        if started:
+            self._notify("CDK_TOOLKIT_I5503", "Stack monitoring complete", action="deploy")
+        if result.code != 0:
+            message = _failure_text(result)
+            failures = describe_failures([f for p in pollers for f in p.failures])
+            if failures:
+                message = f"{message}\n\nResource failures:\n{failures}"
+            raise CdkCommandError(message, result)
+
+        stack_outputs = _read_outputs_file(outputs_file)
+        for name in stack_names or list(stack_outputs):
+            outputs = stack_outputs.get(name, {})
+            self._notify(
+                "CDK_TOOLKIT_I5900",
+                f"✅  {name}",
+                data={"outputs": outputs, "stackName": name},
+                action="deploy",
+            )
+        self._notify("CDK_TOOLKIT_I5901", "Deployment success", action="deploy")
+
+    def _target_stack_names(self, stacks: StackSelector | None) -> list[str]:
+        if stacks is not None and stacks.patterns and not any(ch in p for p in stacks.patterns for ch in "*?"):
+            return list(stacks.patterns)
+        return list(self._stack_names)
+
+    def _template_resource_count(self, stack_name: str) -> int:
+        if not self._assembly_dir:
+            return 0
+        template = read_assembly_template(self._assembly_dir, stack_name)
+        return len((template or {}).get("Resources") or {})
+
+    # -- destroy / diff / list / bootstrap ---------------------------------------------------
+
+    def destroy(self, stacks: StackSelector | None = None) -> None:
+        self._ensure_initialized()
+        result = self._run(["destroy", *self._selection_args(stacks), *self._app_args(), "--force", "--no-notices"])
+        self._forward_output(result, "destroy")
+        if result.code != 0:
+            raise _with_error_context("destroy", CdkCommandError(_failure_text(result), result))
+
+    def diff(self, stacks: StackSelector | None = None) -> None:
+        """Run ``cdk diff``; per-stack blocks go out as I4002, the summary line as I4001."""
+        self._ensure_initialized()
+        # Without --fail, `cdk diff` exits 0 whether or not there are differences.
+        result = self._run(["diff", *self._selection_args(stacks), *self._app_args(), "--no-notices"])
+        if result.code != 0:
+            raise _with_error_context("diff", CdkCommandError(_failure_text(result), result))
+        for code, text in split_diff_output((result.stderr or "") + "\n" + (result.stdout or "")):
+            self._notify(code, text, action="diff")
+
+    def list(self, stacks: StackSelector | None = None) -> list[str]:
+        self._ensure_initialized()
+        result = self._run(["list", *self._selection_args(stacks), *self._app_args(), "--no-notices"])
+        if result.code != 0:
+            raise _with_error_context("list", CdkCommandError(_failure_text(result), result))
+        return [line.strip() for line in (result.stdout or "").splitlines() if line.strip()]
+
+    def bootstrap(self, environments: Sequence[str], kms_key_id: str | None = None) -> None:
+        """Bootstrap the CDK toolkit stack; creates a KMS CMK for the staging bucket by default."""
+        self._ensure_initialized()
+        params = ["--bootstrap-kms-key-id", kms_key_id] if kms_key_id else ["--bootstrap-customer-key"]
+        result = self._run(["bootstrap", *environments, *self._app_args(), *params, "--ci", "--no-notices"])
+        self._forward_output(result, "bootstrap")
+        if result.code != 0:
+            message = _failure_text(result)
+            for env in environments:
+                message += explain_bootstrap_failure(env, self.profile)
+            raise _with_error_context("bootstrap", CdkCommandError(message, result))
+
+
+BOOTSTRAP_STACK_NAME = "CDKToolkit"
+
+
+def explain_bootstrap_failure(environment: str, profile: str | None = None) -> str:
+    """Why the CDKToolkit stack failed, from its CloudFormation events (best effort).
+
+    The cdk CLI often reports only "NoStack: CloudFormationStack object does not hold a stack";
+    the actionable reason (e.g. missing iam:CreateRole) is in the stack events.
+    """
+    match = re.match(r"^aws://([^/]+)/(.+)$", environment)
+    if not match:
+        return ""
+    region = match.group(2)
+    try:
+        from agentcore.aws.account import create_aws_client
+
+        cfn = create_aws_client("cloudformation", region)
+        status = cfn.describe_stacks(StackName=BOOTSTRAP_STACK_NAME)["Stacks"][0]["StackStatus"]
+        events = cfn.describe_stack_events(StackName=BOOTSTRAP_STACK_NAME)["StackEvents"]
+    except Exception:  # noqa: BLE001 - diagnostics only; the original error still surfaces
+        return ""
+
+    reasons: list[str] = []
+    for event in events:  # newest first; stop at the start of the latest attempt
+        if (
+            event.get("LogicalResourceId") == BOOTSTRAP_STACK_NAME
+            and event.get("ResourceStatus", "").endswith("_IN_PROGRESS")
+            and event.get("ResourceStatusReason") == "User Initiated"
+        ):
+            break
+        if event.get("ResourceStatus", "").endswith("_FAILED") and event.get("ResourceStatusReason"):
+            line = f"{event['LogicalResourceId']}: {event['ResourceStatusReason']}"
+            if line not in reasons:
+                reasons.append(line)
+
+    lines: list[str] = []
+    if reasons:
+        lines.append(f"\n\nCloudFormation reported for {BOOTSTRAP_STACK_NAME} in {region}:")
+        lines.extend(f"  - {r}" for r in reasons[:3])
+    if any("iam:" in r and "not authorized" in r for r in reasons):
+        lines.append(
+            "\nYour AWS identity cannot create IAM roles, which CDK bootstrap (and deploy) requires. "
+            "Use a role with IAM permissions, e.g. AdministratorAccess in a sandbox account."
+        )
+    if status in ("ROLLBACK_COMPLETE", "ROLLBACK_FAILED", "DELETE_FAILED"):
+        profile_flag = f" --profile {profile}" if profile else ""
+        lines.append(
+            f"\nThe {BOOTSTRAP_STACK_NAME} stack is in {status} and must be deleted before retrying:\n"
+            f"  aws cloudformation delete-stack --stack-name {BOOTSTRAP_STACK_NAME} --region {region}{profile_flag}"
+        )
+    return "\n".join(lines)
+
+
+def create_cdk_toolkit_wrapper(
+    project_dir: str | os.PathLike[str] | None = None,
+    *,
+    io_host: IoHost | None = None,
+    profile: str | None = None,
+    region: str | None = None,
+    **kwargs: Any,
+) -> CdkToolkitWrapper:
+    """Create and initialize a :class:`CdkToolkitWrapper`."""
+    wrapper = CdkToolkitWrapper(project_dir, io_host=io_host, profile=profile, region=region, **kwargs)
+    wrapper.initialize()
+    return wrapper
+
+
+# ---------------------------------------------------------------------------
+# Cloud assembly helpers
+# ---------------------------------------------------------------------------
+
+
+def _read_json(path: Path) -> Any:
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return None
+
+
+def _stack_artifacts(assembly_dir: str | os.PathLike[str]) -> list[tuple[str, dict[str, Any]]]:
+    manifest = _read_json(Path(assembly_dir) / "manifest.json") or {}
+    artifacts = manifest.get("artifacts") or {}
+    return [
+        (artifact_id, artifact)
+        for artifact_id, artifact in artifacts.items()
+        if isinstance(artifact, dict) and artifact.get("type") == "aws:cloudformation:stack"
+    ]
+
+
+def read_assembly_stack_names(assembly_dir: str | os.PathLike[str]) -> list[str]:
+    """Stack names in a synthesized cloud assembly (``manifest.json``), in manifest order."""
+    names = []
+    for artifact_id, artifact in _stack_artifacts(assembly_dir):
+        props = artifact.get("properties") or {}
+        names.append(props.get("stackName") or artifact.get("displayName") or artifact_id)
+    return names
+
+
+def read_assembly_template(assembly_dir: str | os.PathLike[str], stack_name: str) -> dict[str, Any] | None:
+    for artifact_id, artifact in _stack_artifacts(assembly_dir):
+        props = artifact.get("properties") or {}
+        if (props.get("stackName") or artifact_id) == stack_name:
+            template_file = props.get("templateFile") or f"{artifact_id}.template.json"
+            return _read_json(Path(assembly_dir) / template_file)
+    return None
+
+
+def _read_outputs_file(path: str) -> dict[str, dict[str, str]]:
+    data = _read_json(Path(path))
+    if not isinstance(data, dict):
+        return {}
+    return {k: {str(ok): str(ov) for ok, ov in v.items()} for k, v in data.items() if isinstance(v, dict)}
+
+
+_DIFF_SUMMARY_RE = re.compile(r"Number of stacks with differences:\s*\d+")
+
+
+def split_diff_output(text: str) -> list[tuple[str, str]]:
+    """Split ``cdk diff`` output into per-stack blocks (I4002) and the summary line (I4001)."""
+    clean = _strip_ansi(text)
+    messages: list[tuple[str, str]] = []
+    current: list[str] = []
+    summary: str | None = None
+    for line in clean.splitlines():
+        if _DIFF_SUMMARY_RE.search(line):
+            summary = line.strip()
+            continue
+        if line.startswith("Stack "):
+            if any(item.strip() for item in current):
+                messages.append(("CDK_TOOLKIT_I4002", "\n".join(current).strip("\n")))
+            current = [line]
+            continue
+        if current:
+            current.append(line)
+    if any(item.strip() for item in current):
+        messages.append(("CDK_TOOLKIT_I4002", "\n".join(current).strip("\n")))
+    if summary:
+        messages.append(("CDK_TOOLKIT_I4001", summary))
+    return messages
+
+
+__all__ = [
+    "CDK_APP_COMMAND",
+    "CDK_OUT_DIR",
+    "DEPLOY_MESSAGE_CODES",
+    "CdkCommandError",
+    "CdkToolkitWrapper",
+    "DeployMessage",
+    "IoHost",
+    "IoMessage",
+    "ResourceProgress",
+    "StackSelectionStrategy",
+    "StackSelector",
+    "SwitchableIoHost",
+    "SynthOutput",
+    "create_cdk_toolkit_wrapper",
+    "create_switchable_io_host",
+    "extract_progress_from_message",
+    "pattern_must_match",
+    "read_assembly_stack_names",
+    "read_assembly_template",
+    "resolve_cdk_command",
+    "silent_io_host",
+    "split_diff_output",
+]