agentcore-cli 0.31.1__py3-none-any.whl

agentcore/cloudformation/stack_events.py

@@ -0,0 +1,107 @@
+"""Poll CloudFormation stack events for deploy progress.
+
+Upstream receives resource-level progress from ``@aws-cdk/toolkit-lib``'s stack activity monitor
+(``CDK_TOOLKIT_I5502`` messages). The Python port drives the ``cdk`` CLI as a subprocess, so it
+reproduces that stream by polling ``DescribeStackEvents`` while the deploy runs.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from typing import Any
+
+from agentcore.aws.account import create_aws_client
+from agentcore.cloudformation.types import is_failure_event
+
+# Clock skew allowance when deciding whether an event belongs to the current operation.
+_SKEW_SECONDS = 5
+
+
+def format_event_time(ts: datetime) -> str:
+    """``Date#toLocaleTimeString()`` in en-US form (``3:04:05 PM``)."""
+    local = ts.astimezone()
+    hour = local.hour % 12 or 12
+    return f"{hour}:{local.minute:02d}:{local.second:02d} {'AM' if local.hour < 12 else 'PM'}"
+
+
+def format_stack_event(stack_name: str, event: dict[str, Any], completed: int, total: int) -> str:
+    """One activity line shaped like CDK's: ``Stack | 3/12 | 3:04:05 PM | STATUS | Type | LogicalId``."""
+    ts = event.get("Timestamp")
+    time_text = format_event_time(ts) if isinstance(ts, datetime) else ""
+    status = event.get("ResourceStatus") or ""
+    line = (
+        f"{stack_name} | {completed}/{total} | {time_text} | {status:<20} | "
+        f"{event.get('ResourceType') or ''} | {event.get('LogicalResourceId') or ''}"
+    )
+    reason = event.get("ResourceStatusReason")
+    if reason and is_failure_event(event):
+        line += f" {reason}"
+    return line
+
+
+@dataclass
+class StackEventPoller:
+    """Incrementally fetch new events for one stack, oldest first, starting at ``since``."""
+
+    region: str
+    stack_name: str
+    since: datetime = field(default_factory=lambda: datetime.now(UTC))
+    seen: set[str] = field(default_factory=set)
+    failures: list[dict[str, Any]] = field(default_factory=list)
+    _client: Any = None
+
+    def _cfn(self) -> Any:
+        if self._client is None:
+            self._client = create_aws_client("cloudformation", self.region)
+        return self._client
+
+    def poll(self) -> list[dict[str, Any]]:
+        """New events since the last poll (best effort: a missing stack or API error yields ``[]``)."""
+        fresh: list[dict[str, Any]] = []
+        token: str | None = None
+        try:
+            while True:
+                params: dict[str, Any] = {"StackName": self.stack_name}
+                if token:
+                    params["NextToken"] = token
+                response = self._cfn().describe_stack_events(**params)
+                stop = False
+                for event in response.get("StackEvents") or []:  # newest first
+                    event_id = event.get("EventId")
+                    ts = event.get("Timestamp")
+                    if isinstance(ts, datetime):
+                        aware = ts if ts.tzinfo else ts.replace(tzinfo=UTC)
+                        if (self.since - aware).total_seconds() > _SKEW_SECONDS:
+                            stop = True
+                            break
+                    if not event_id or event_id in self.seen:
+                        stop = True
+                        break
+                    fresh.append(event)
+                token = response.get("NextToken")
+                if stop or not token:
+                    break
+        except Exception:  # noqa: BLE001 - progress is best-effort (ValidationError: stack not created yet)
+            return []
+        fresh.reverse()
+        for event in fresh:
+            self.seen.add(event["EventId"])
+            if is_failure_event(event):
+                self.failures.append(event)
+        return fresh
+
+
+def describe_failures(failures: list[dict[str, Any]]) -> str:
+    """Human summary of failed resource events (empty string when none)."""
+    lines = []
+    for event in failures:
+        reason = event.get("ResourceStatusReason") or "(no reason given)"
+        lines.append(
+            f"  {event.get('LogicalResourceId') or '?'} ({event.get('ResourceType') or '?'}) "
+            f"{event.get('ResourceStatus') or ''}: {reason}"
+        )
+    return "\n".join(lines)
+
+
+__all__ = ["StackEventPoller", "describe_failures", "format_event_time", "format_stack_event"]

agentcore/cloudformation/stack_status.py

@@ -0,0 +1,98 @@
+"""Stack deployability checks (port of ``cloudformation/stack-status.ts``)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from agentcore.aws._aws_errors import aws_error_name
+from agentcore.aws.account import create_aws_client
+
+# Transitional states: the stack can't be updated until the current operation completes.
+IN_PROGRESS_STATUSES = frozenset(
+    {
+        "CREATE_IN_PROGRESS",
+        "UPDATE_IN_PROGRESS",
+        "DELETE_IN_PROGRESS",
+        "ROLLBACK_IN_PROGRESS",
+        "UPDATE_ROLLBACK_IN_PROGRESS",
+        "UPDATE_COMPLETE_CLEANUP_IN_PROGRESS",
+        "DELETE_COMPLETE_CLEANUP_IN_PROGRESS",
+        "REVIEW_IN_PROGRESS",
+        "IMPORT_IN_PROGRESS",
+        "IMPORT_ROLLBACK_IN_PROGRESS",
+    }
+)
+
+# Failed states that may require manual intervention.
+FAILED_STATUSES = frozenset(
+    {"CREATE_FAILED", "ROLLBACK_FAILED", "DELETE_FAILED", "UPDATE_ROLLBACK_FAILED", "IMPORT_ROLLBACK_FAILED"}
+)
+
+
+@dataclass(frozen=True)
+class StackStatusResult:
+    can_deploy: bool
+    exists: bool
+    status: str | None = None
+    message: str | None = None
+
+
+@dataclass(frozen=True)
+class BlockingStack:
+    stack_name: str
+    result: StackStatusResult
+
+
+def check_stack_status(region: str, stack_name: str) -> StackStatusResult:
+    """Whether ``stack_name`` can be deployed to (missing or stable stacks can)."""
+    cfn = create_aws_client("cloudformation", region)
+    try:
+        resp = cfn.describe_stacks(StackName=stack_name)
+    except Exception as exc:
+        # Stack doesn't exist - safe to deploy (will create new stack)
+        if aws_error_name(exc) == "ValidationError":
+            return StackStatusResult(can_deploy=True, exists=False)
+        raise
+
+    stacks = resp.get("Stacks") or []
+    status = stacks[0].get("StackStatus") if stacks else None
+    if not status:
+        return StackStatusResult(can_deploy=True, exists=True)
+
+    if status in IN_PROGRESS_STATUSES:
+        return StackStatusResult(
+            can_deploy=False,
+            exists=True,
+            status=status,
+            message=(
+                f'Stack "{stack_name}" is currently in {status} state. '
+                "Please wait for the operation to complete before deploying."
+            ),
+        )
+    if status in FAILED_STATUSES:
+        return StackStatusResult(
+            can_deploy=False,
+            exists=True,
+            status=status,
+            message=f'Stack "{stack_name}" is in {status} state. Manual intervention may be required before deploying.',
+        )
+    return StackStatusResult(can_deploy=True, exists=True, status=status)
+
+
+def check_stacks_status(region: str, stack_names: list[str]) -> BlockingStack | None:
+    """The first stack that blocks deployment, or None when all are deployable."""
+    for stack_name in stack_names:
+        result = check_stack_status(region, stack_name)
+        if not result.can_deploy:
+            return BlockingStack(stack_name=stack_name, result=result)
+    return None
+
+
+__all__ = [
+    "FAILED_STATUSES",
+    "IN_PROGRESS_STATUSES",
+    "BlockingStack",
+    "StackStatusResult",
+    "check_stack_status",
+    "check_stacks_status",
+]

agentcore/cloudformation/types.py

@@ -0,0 +1,44 @@
+"""Stack status helpers shared by progress rendering (port of ``cloudformation/types.ts``)."""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+TERMINAL_STACK_STATUSES = frozenset(
+    {
+        "CREATE_COMPLETE",
+        "UPDATE_COMPLETE",
+        "UPDATE_ROLLBACK_COMPLETE",
+        "ROLLBACK_COMPLETE",
+        "CREATE_FAILED",
+        "DELETE_FAILED",
+        "DELETE_COMPLETE",
+        "UPDATE_ROLLBACK_FAILED",
+        "ROLLBACK_FAILED",
+        "IMPORT_COMPLETE",
+        "IMPORT_ROLLBACK_COMPLETE",
+        "IMPORT_ROLLBACK_FAILED",
+    }
+)
+
+
+def failure_like(status: str | None) -> bool:
+    """Port of ``FAILURE_LIKE``."""
+    return bool(status) and (status.endswith("_FAILED") or "ROLLBACK" in status or status == "DELETE_FAILED")
+
+
+def get_status_color(status: str) -> Literal["green", "red", "yellow", "white"]:
+    if "COMPLETE" in status and "ROLLBACK" not in status:
+        return "green"
+    if "FAILED" in status or "ROLLBACK" in status:
+        return "red"
+    if "PROGRESS" in status:
+        return "yellow"
+    return "white"
+
+
+def is_failure_event(event: dict[str, Any]) -> bool:
+    return (event.get("ResourceStatus") or "").endswith("FAILED")
+
+
+__all__ = ["TERMINAL_STACK_STATUSES", "failure_like", "get_status_color", "is_failure_event"]

agentcore/lib/__init__.py

@@ -0,0 +1,68 @@
+"""Shared library layer (port of upstream ``src/lib``).
+
+Schema models are not re-exported here (upstream re-exports ``src/schema``); import them from
+``agentcore.schema``.
+"""
+
+from agentcore.lib.constants import (
+    APP_DIR,
+    CLI_LOGS_DIR,
+    CLI_SYSTEM_DIR,
+    CONFIG_DIR,
+    CONFIG_FILES,
+    CONTAINER_INTERNAL_PORT,
+    CONTAINER_RUNTIMES,
+    DEFAULT_PYTHON_PLATFORM,
+    DOCKERFILE_NAME,
+    ENV_FILE,
+    MCP_APP_SUBDIR,
+    ONE_GB,
+    UV_INSTALL_HINT,
+    ContainerRuntime,
+    get_artifact_zip_name,
+    get_dockerfile_path,
+)
+from agentcore.lib.errors import *  # noqa: F403
+from agentcore.lib.errors import __all__ as _errors_all
+from agentcore.lib.packaging import *  # noqa: F403
+from agentcore.lib.packaging import __all__ as _packaging_all
+from agentcore.lib.result import Err, Ok, Result, err, ok, serialize_result, unwrap_result
+from agentcore.lib.schemas.io import *  # noqa: F403
+from agentcore.lib.schemas.io import __all__ as _io_all
+from agentcore.lib.time_constants import ONE_DAY_MS, ONE_HOUR_MS, ONE_MINUTE_MS, ONE_SECOND_MS
+from agentcore.lib.utils import *  # noqa: F403
+from agentcore.lib.utils import __all__ as _utils_all
+
+__all__ = [
+    "APP_DIR",
+    "CLI_LOGS_DIR",
+    "CLI_SYSTEM_DIR",
+    "CONFIG_DIR",
+    "CONFIG_FILES",
+    "CONTAINER_INTERNAL_PORT",
+    "CONTAINER_RUNTIMES",
+    "DEFAULT_PYTHON_PLATFORM",
+    "DOCKERFILE_NAME",
+    "ENV_FILE",
+    "MCP_APP_SUBDIR",
+    "ONE_DAY_MS",
+    "ONE_GB",
+    "ONE_HOUR_MS",
+    "ONE_MINUTE_MS",
+    "ONE_SECOND_MS",
+    "UV_INSTALL_HINT",
+    "ContainerRuntime",
+    "Err",
+    "Ok",
+    "Result",
+    "err",
+    "get_artifact_zip_name",
+    "get_dockerfile_path",
+    "ok",
+    "serialize_result",
+    "unwrap_result",
+    *_errors_all,
+    *_packaging_all,
+    *_io_all,
+    *_utils_all,
+]

agentcore/lib/constants.py

@@ -0,0 +1,77 @@
+"""Shared constants (port of ``src/lib/constants.ts``)."""
+
+from __future__ import annotations
+
+import os
+import re
+from typing import Final, Literal
+
+# Configuration directory and file names
+CONFIG_DIR: Final = "agentcore"
+
+# Application code directory (for generated agents and MCP tools)
+APP_DIR: Final = "app"
+MCP_APP_SUBDIR: Final = "mcp"
+
+HARNESS_DIR: Final = "harnesses"
+
+# CLI system subdirectory (inside CONFIG_DIR)
+CLI_SYSTEM_DIR: Final = ".cli"
+CLI_LOGS_DIR: Final = "logs"
+
+
+class CONFIG_FILES:  # noqa: N801 - mirrors the upstream constant object
+    AGENT_ENV: Final = "agentcore.json"
+    AWS_TARGETS: Final = "aws-targets.json"
+    DEPLOYED_STATE: Final = "deployed-state.json"
+    MCP_DEFS: Final = "mcp-defs.json"
+
+
+# Environment file for secrets (API keys, etc.) - local only, not committed
+ENV_FILE: Final = ".env.local"
+
+
+def get_artifact_zip_name(name: str) -> str:
+    return f"{name}.zip"
+
+
+UV_INSTALL_HINT: Final = "Install uv from https://github.com/astral-sh/uv#installation and ensure it is on your PATH."
+NPM_INSTALL_HINT: Final = "Install npm from https://nodejs.org/ and ensure it is on your PATH."
+DEFAULT_PYTHON_PLATFORM: Final = "aarch64-manylinux2014"
+
+# Container constants
+ONE_GB: Final = 1024 * 1024 * 1024
+DOCKERFILE_NAME: Final = "Dockerfile"
+CONTAINER_INTERNAL_PORT: Final = 8080
+
+ContainerRuntime = Literal["docker", "podman", "finch"]
+# Supported container runtimes in order of preference.
+CONTAINER_RUNTIMES: Final[tuple[ContainerRuntime, ...]] = ("docker", "podman", "finch")
+
+_DOCKERFILE_PATH_ALLOWED_CHARS = re.compile(r"[A-Za-z0-9._/-]+")
+
+
+def is_valid_dockerfile_path(p: str) -> bool:
+    """Same rule as the schema's ``isValidDockerfilePath``: a safe relative path in the build context."""
+    try:
+        from agentcore.schema import is_valid_dockerfile_path as schema_check  # type: ignore[attr-defined]
+    except Exception:  # schema package absent or not importable
+        schema_check = None
+    if schema_check is not None:
+        return bool(schema_check(p))
+    if not _DOCKERFILE_PATH_ALLOWED_CHARS.fullmatch(p):
+        return False
+    if p.startswith("/"):
+        return False
+    return not any(segment in ("", "..") for segment in p.split("/"))
+
+
+def get_dockerfile_path(build_context: str, dockerfile: str | None = None) -> str:
+    """Resolve the Dockerfile path against the Docker build context, rejecting escapes."""
+    name = dockerfile if dockerfile is not None else DOCKERFILE_NAME
+    if not is_valid_dockerfile_path(name):
+        raise ValueError(
+            f'Invalid dockerfile path "{name}": must be a relative path within the build context (a filename or '
+            'forward-slash subpath; no leading slash, backslash, empty segments, or ".." traversal)'
+        )
+    return os.path.join(build_context, name)

agentcore/lib/dependency_management/__init__.py

@@ -0,0 +1,23 @@
+from agentcore.lib.dependency_management.plan import SkewFinding, SyncPlan, compute_sync_plan
+from agentcore.lib.dependency_management.sync import sync_managed_dependencies
+from agentcore.lib.dependency_management.types import (
+    DependencyChange,
+    DependencySyncOutcome,
+    DependencySyncResult,
+    PackageManifest,
+    RestoredDependency,
+    SkippedDependency,
+)
+
+__all__ = [
+    "DependencyChange",
+    "DependencySyncOutcome",
+    "DependencySyncResult",
+    "PackageManifest",
+    "RestoredDependency",
+    "SkewFinding",
+    "SkippedDependency",
+    "SyncPlan",
+    "compute_sync_plan",
+    "sync_managed_dependencies",
+]

agentcore/lib/dependency_management/messages.py

@@ -0,0 +1,92 @@
+"""User-facing wording for dependency management (port of ``messages.ts``)."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from agentcore.lib.dependency_management.plan import SkewFinding
+from agentcore.lib.dependency_management.types import DependencyChange, RestoredDependency, SkippedDependency
+
+# Fallback when the CLI layer doesn't pass its distro-aware install command.
+DEFAULT_CLI_INSTALL_COMMAND = "npm install -g @aws/agentcore@latest"
+
+OPT_OUT_HINT = "To manage these versions yourself: agentcore config disableDependencyManagement true"
+
+_MIGRATION_PREAMBLE = (
+    "Your project was created before the AgentCore CLI managed dependency versions.\n"
+    "We've updated agentcore/cdk/package.json so the CLI keeps these dependencies\n"
+    "on versions it has been tested with (patch updates still apply automatically):"
+)
+
+# Check-mode variant: nothing was written, so promise rather than claim.
+_MIGRATION_PREAMBLE_PENDING = (
+    "Your project was created before the AgentCore CLI managed dependency versions.\n"
+    "agentcore/cdk/package.json will be updated on the next deploy so the CLI keeps these\n"
+    "dependencies on versions it has been tested with (patch updates still apply automatically):"
+)
+
+
+def _format_skew_list(skew: Sequence[SkewFinding]) -> str:
+    return ", ".join(f"{s.name} ({s.declared}, CLI expects {s.expected})" for s in skew)
+
+
+def format_cli_upgrade_error(skew: Sequence[SkewFinding], install_command: str) -> str:
+    plural = len(skew) > 1
+    return (
+        f"This project requires a newer version of the AgentCore CLI: {_format_skew_list(skew)} "
+        f"{'are' if plural else 'is'} newer than this CLI was tested with. "
+        f"Run `{install_command}` and retry.\n"
+        f"If you intentionally updated {'these dependencies' if plural else 'this dependency'} yourself, "
+        "you can disable managed dependency versions instead:\n" + OPT_OUT_HINT
+    )
+
+
+def _format_change_table(changes: Sequence[DependencyChange], restored: Sequence[RestoredDependency]) -> str:
+    rows = [(c.name, c.from_, c.to) for c in changes] + [(r.name, "(removed)", r.to) for r in restored]
+    name_width = max(len(r[0]) for r in rows)
+    from_width = max(len(r[1]) for r in rows)
+    return "\n".join(f"  {name.ljust(name_width)}  {frm.ljust(from_width)} → {to}" for name, frm, to in rows)
+
+
+def format_sync_notice(
+    *,
+    migrated_from_caret: bool,
+    changes: Sequence[DependencyChange],
+    restored: Sequence[RestoredDependency],
+    reinstalled: bool,
+    applied: bool,
+) -> str | None:
+    """Notice summarising managed-dependency updates; ``applied=False`` (check mode) uses future tense."""
+    if not changes and not restored:
+        return None
+    lines: list[str] = []
+    if migrated_from_caret:
+        lines.append(_MIGRATION_PREAMBLE if applied else _MIGRATION_PREAMBLE_PENDING)
+    else:
+        lines.append(
+            "Updated managed dependencies in agentcore/cdk/package.json:"
+            if applied
+            else "Managed dependencies in agentcore/cdk/package.json will be updated on the next deploy:"
+        )
+    lines += ["", _format_change_table(changes, restored), ""]
+    if reinstalled:
+        lines.append("Ran npm install in agentcore/cdk to apply the updates.")
+    lines.append(
+        "Dependencies you added yourself were not changed."
+        if applied
+        else "Dependencies you added yourself will not be changed."
+    )
+    if migrated_from_caret:
+        lines.append(OPT_OUT_HINT)
+    return "\n".join(lines)
+
+
+def format_skew_warning(skew: Sequence[SkewFinding], install_command: str) -> str:
+    return (
+        f"{_format_skew_list(skew)} {'is' if len(skew) == 1 else 'are'} newer than this CLI was tested with; "
+        f"deploy may fail — upgrade the CLI with `{install_command}`. {OPT_OUT_HINT}"
+    )
+
+
+def format_skipped_warning(skipped: SkippedDependency) -> str:
+    return f"{skipped.name} ({skipped.raw}) {skipped.reason}."

agentcore/lib/dependency_management/plan.py

@@ -0,0 +1,98 @@
+"""Pure managed-dependency sync policy (port of ``plan.ts``). No I/O.
+
+A dependency is managed iff it is named in the vended manifest; its vended specifier is
+authoritative and copied verbatim.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Any
+
+from agentcore.lib.dependency_management.semver import ParsedSpecifier, compare, parse_specifier
+from agentcore.lib.dependency_management.types import (
+    DependencyChange,
+    DependencySection,
+    RestoredDependency,
+    SkippedDependency,
+)
+
+_SECTIONS: tuple[DependencySection, ...] = ("dependencies", "devDependencies")
+
+
+@dataclass(frozen=True, slots=True)
+class SkewFinding:
+    name: str
+    declared: str
+    expected: str
+
+
+@dataclass(slots=True)
+class SyncPlan:
+    # Managed deps where the project declares a newer minor/major than the CLI expects.
+    skew: list[SkewFinding] = field(default_factory=list)
+    changes: list[DependencyChange] = field(default_factory=list)
+    restored: list[RestoredDependency] = field(default_factory=list)
+    skipped: list[SkippedDependency] = field(default_factory=list)
+    # Any managed dep had a caret range: the project predates pinning.
+    migrated_from_caret: bool = False
+
+
+def _find_declared(manifest: Mapping[str, Any], name: str) -> tuple[DependencySection, str] | None:
+    for section in _SECTIONS:
+        deps = manifest.get(section) or {}
+        if name in deps and deps[name] is not None:
+            return section, deps[name]
+    return None
+
+
+def _is_skewed(declared: ParsedSpecifier, expected: ParsedSpecifier) -> bool:
+    """Declared is ahead in a way patch-floating can't explain: higher major.minor for ranges, or
+    any prerelease-aware greater-than for exact pins (so alpha.20 never drops to alpha.19)."""
+    if declared.version is None or expected.version is None:
+        return False
+    d, e = declared.version, expected.version
+    if expected.kind == "exact":
+        return compare(d, e) > 0
+    if d.major != e.major:
+        return d.major > e.major
+    return d.minor > e.minor
+
+
+def compute_sync_plan(vended: Mapping[str, Any], project: Mapping[str, Any]) -> SyncPlan:
+    plan = SyncPlan()
+    for section in _SECTIONS:
+        for name, expected_raw in (vended.get(section) or {}).items():
+            expected = parse_specifier(expected_raw)
+            declared = _find_declared(project, name)
+
+            if declared is None:
+                # Deleted by the user; the vended CDK app can't build without it.
+                plan.restored.append(RestoredDependency(name=name, section=section, to=expected_raw))
+                continue
+
+            declared_section, declared_raw = declared
+            if declared_raw == expected_raw:
+                continue
+
+            declared_spec = parse_specifier(declared_raw)
+            if declared_spec.kind == "unsupported":
+                # file:/git:/tag/range specifiers are deliberate local overrides.
+                plan.skipped.append(
+                    SkippedDependency(
+                        name=name, raw=declared_raw, reason="uses a non-semver specifier and was left unmanaged"
+                    )
+                )
+                continue
+
+            if _is_skewed(declared_spec, expected):
+                plan.skew.append(SkewFinding(name=name, declared=declared_raw, expected=expected_raw))
+                continue
+
+            if declared_spec.kind == "caret":
+                plan.migrated_from_caret = True
+            plan.changes.append(
+                DependencyChange(name=name, section=declared_section, from_=declared_raw, to=expected_raw)
+            )
+    return plan