agentcore-cli 0.31.1__py3-none-any.whl

agentcore/lib/dependency_management/semver.py

@@ -0,0 +1,137 @@
+"""Strict semver parsing/comparison with node-semver semantics (port of ``semver.ts``).
+
+PEP 440 (``packaging.version``) orders prereleases differently and accepts other syntax, so
+node-semver's ``parse`` (non-loose) and ``compare`` are reimplemented here.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from functools import total_ordering
+from typing import Literal
+
+_MAX_LENGTH = 256
+_MAX_SAFE_INTEGER = 2**53 - 1
+
+_NUM = r"0|[1-9]\d*"
+_PRERELEASE_ID = rf"(?:{_NUM}|\d*[a-zA-Z-][a-zA-Z0-9-]*)"
+_FULL = re.compile(
+    rf"^v?({_NUM})\.({_NUM})\.({_NUM})"
+    rf"(?:-({_PRERELEASE_ID}(?:\.{_PRERELEASE_ID})*))?"
+    r"(?:\+([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?$"
+)
+
+
+@total_ordering
+@dataclass(frozen=True, slots=True)
+class SemVer:
+    major: int
+    minor: int
+    patch: int
+    prerelease: tuple[int | str, ...] = ()
+    build: tuple[str, ...] = ()
+
+    @property
+    def version(self) -> str:
+        v = f"{self.major}.{self.minor}.{self.patch}"
+        return v + ("-" + ".".join(str(p) for p in self.prerelease) if self.prerelease else "")
+
+    def __str__(self) -> str:
+        return self.version
+
+    def compare(self, other: SemVer) -> int:
+        return compare(self, other)
+
+    def __eq__(self, other: object) -> bool:
+        return isinstance(other, SemVer) and compare(self, other) == 0
+
+    def __lt__(self, other: SemVer) -> bool:
+        return compare(self, other) < 0
+
+    def __hash__(self) -> int:
+        return hash((self.major, self.minor, self.patch, self.prerelease))
+
+
+def parse(version: str) -> SemVer | None:
+    """node-semver ``parse(version, { loose: false })``: ``None`` if invalid."""
+    if not isinstance(version, str) or len(version) > _MAX_LENGTH:
+        return None
+    match = _FULL.match(version.strip())
+    if not match:
+        return None
+    major, minor, patch = (int(match.group(i)) for i in (1, 2, 3))
+    if max(major, minor, patch) > _MAX_SAFE_INTEGER:
+        return None
+    prerelease: tuple[int | str, ...] = ()
+    if match.group(4):
+        prerelease = tuple(
+            int(p) if p.isdigit() and int(p) <= _MAX_SAFE_INTEGER else p for p in match.group(4).split(".")
+        )
+    build = tuple(match.group(5).split(".")) if match.group(5) else ()
+    return SemVer(major, minor, patch, prerelease, build)
+
+
+def _cmp(a: int | str, b: int | str) -> int:
+    return (a > b) - (a < b)  # type: ignore[operator]
+
+
+def _compare_identifiers(a: int | str, b: int | str) -> int:
+    a_num, b_num = isinstance(a, int), isinstance(b, int)
+    if a_num and b_num:
+        return _cmp(a, b)
+    if a_num:
+        return -1
+    if b_num:
+        return 1
+    return _cmp(a, b)
+
+
+def compare(a: SemVer, b: SemVer) -> int:
+    """-1/0/1 by main version then prerelease precedence; build metadata ignored."""
+    main = _cmp((a.major, a.minor, a.patch), (b.major, b.minor, b.patch))  # type: ignore[arg-type]
+    if main:
+        return main
+    if a.prerelease and not b.prerelease:
+        return -1
+    if not a.prerelease and b.prerelease:
+        return 1
+    for x, y in zip(a.prerelease, b.prerelease, strict=False):
+        c = _compare_identifiers(x, y)
+        if c:
+            return c
+    return _cmp(len(a.prerelease), len(b.prerelease))
+
+
+ParsedVersion = SemVer
+SpecifierKind = Literal["exact", "tilde", "caret"]
+
+
+@dataclass(frozen=True, slots=True)
+class ParsedSpecifier:
+    kind: Literal["exact", "tilde", "caret", "unsupported"]
+    raw: str
+    version: SemVer | None = None
+
+
+def parse_version(version: str) -> SemVer | None:
+    # npm accepts a leading 'v' or 'V'; node-semver only the lowercase form.
+    normalized = re.sub(r"^V", "v", version.strip())
+    return parse(normalized)
+
+
+def parse_specifier(raw: str) -> ParsedSpecifier:
+    """Classify an npm specifier as exact / tilde / caret, or unsupported (file:, git:, tags, ranges)."""
+    trimmed = raw.strip()
+    kind: SpecifierKind = "exact"
+    version_part = trimmed
+    if trimmed.startswith("~"):
+        kind, version_part = "tilde", trimmed[1:]
+    elif trimmed.startswith("^"):
+        kind, version_part = "caret", trimmed[1:]
+    elif trimmed.startswith("="):
+        version_part = trimmed[1:]
+    version = parse_version(version_part)
+    if version is None:
+        return ParsedSpecifier(kind="unsupported", raw=raw)
+    return ParsedSpecifier(kind=kind, raw=raw, version=version)

agentcore/lib/dependency_management/sync.py

@@ -0,0 +1,139 @@
+"""Sync a vended CDK project's managed dependencies (port of ``sync.ts``)."""
+
+from __future__ import annotations
+
+import json
+import os
+from typing import Any, Literal
+
+from agentcore.lib.dependency_management.messages import (
+    DEFAULT_CLI_INSTALL_COMMAND,
+    format_cli_upgrade_error,
+    format_skew_warning,
+    format_skipped_warning,
+    format_sync_notice,
+)
+from agentcore.lib.dependency_management.plan import compute_sync_plan
+from agentcore.lib.dependency_management.types import DependencySyncResult
+from agentcore.lib.errors.types import CliVersionTooOldError, DependencySyncError
+from agentcore.lib.utils.json_format import to_json_string
+from agentcore.lib.utils.subprocess import run_subprocess_capture
+
+
+def _read_manifest(path: str, description: str) -> tuple[dict[str, Any], str]:
+    try:
+        with open(path, encoding="utf-8") as fh:
+            raw = fh.read()
+    except OSError as exc:
+        raise DependencySyncError(f"Could not read {description} at {path}: {exc}", cause=exc) from exc
+    try:
+        return json.loads(raw), raw
+    except ValueError as exc:
+        raise DependencySyncError(f"Could not parse {description} at {path}: {exc}", cause=exc) from exc
+
+
+def _write_text(path: str, content: str) -> None:
+    with open(path, "w", encoding="utf-8", newline="") as fh:
+        fh.write(content)
+
+
+def sync_managed_dependencies(
+    *,
+    vended_package_json_path: str,
+    project_dir: str,
+    disabled: bool = False,
+    mode: Literal["apply", "check"] = "apply",
+    treat_skew_as_warning: bool = False,
+    install_command: str = DEFAULT_CLI_INSTALL_COMMAND,
+) -> DependencySyncResult:
+    """Pin the CDK project's managed dependencies to the versions this CLI release was tested with.
+
+    The vended package.json is the source of truth; other dependencies are untouched. A managed
+    dependency newer than the CLI expects raises ``CliVersionTooOldError`` (a warning when
+    ``disabled`` / ``treat_skew_as_warning`` / check mode). When anything changed or
+    ``node_modules`` is missing, ``npm install`` runs; on failure the original package.json is
+    restored so a retry recomputes the same plan. ``mode="check"`` never writes or installs.
+    """
+    check_only = mode == "check"
+    project_package_json = os.path.join(project_dir, "package.json")
+
+    vended, _ = _read_manifest(vended_package_json_path, "the vended CDK package.json")
+    project, project_raw = _read_manifest(project_package_json, "the project's CDK package.json")
+
+    plan = compute_sync_plan(vended, project)
+
+    # `disabled` wins over check mode: an opted-out sync never writes.
+    outcome = "opted-out" if disabled else "check-only" if check_only else "synced"
+    result = DependencySyncResult(
+        outcome=outcome,
+        opted_out=disabled,
+        check_only=check_only,
+        migrated_from_caret=plan.migrated_from_caret,
+        reinstalled=False,
+        skew_warning=False,
+        changes=plan.changes,
+        restored=plan.restored,
+        skipped=plan.skipped,
+        warnings=[format_skipped_warning(s) for s in plan.skipped],
+        notice=None,
+    )
+
+    if plan.skew:
+        if not disabled and not treat_skew_as_warning and not check_only:
+            raise CliVersionTooOldError(format_cli_upgrade_error(plan.skew, install_command))
+        result.skew_warning = True
+        result.warnings.append(format_skew_warning(plan.skew, install_command))
+
+    if disabled:
+        return result
+
+    has_planned_changes = bool(plan.changes or plan.restored)
+
+    if check_only:
+        result.notice = format_sync_notice(
+            migrated_from_caret=result.migrated_from_caret,
+            changes=result.changes,
+            restored=result.restored,
+            reinstalled=False,
+            applied=False,
+        )
+        return result
+
+    if has_planned_changes:
+        # Mutate the parsed manifest in place so user key order and unknown fields survive.
+        for change in plan.changes:
+            project.setdefault(change.section, {})[change.name] = change.to
+        for restored in plan.restored:
+            project.setdefault(restored.section, {})[restored.name] = restored.to
+        try:
+            _write_text(project_package_json, to_json_string(project, 2) + "\n")
+        except OSError as exc:
+            raise DependencySyncError(f"Failed to update the CDK project's dependencies: {exc}", cause=exc) from exc
+
+    # npm reconciles the edited manifest against the existing lockfile incrementally, so
+    # node_modules and the lockfile are never deleted.
+    needs_install = has_planned_changes or not os.path.exists(os.path.join(project_dir, "node_modules"))
+    if not needs_install:
+        return result
+
+    install = run_subprocess_capture("npm", ["install"], cwd=project_dir)
+    if install.code != 0:
+        # Restore the pre-rewrite manifest so a retry recomputes the same plan and re-installs,
+        # instead of deploying against a stale tree. Best-effort.
+        if has_planned_changes:
+            try:
+                _write_text(project_package_json, project_raw)
+            except OSError:
+                pass
+        raise DependencySyncError(
+            f"npm install failed after updating managed dependencies (exit {'null' if install.code is None else install.code}): {install.stderr}"
+        )
+    result.reinstalled = True
+    result.notice = format_sync_notice(
+        migrated_from_caret=result.migrated_from_caret,
+        changes=result.changes,
+        restored=result.restored,
+        reinstalled=True,
+        applied=True,
+    )
+    return result

agentcore/lib/dependency_management/types.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+DependencySection = Literal["dependencies", "devDependencies"]
+
+# A package.json document; unknown fields are preserved verbatim.
+PackageManifest = dict[str, Any]
+
+# - synced: apply mode ran; check-only: plan computed, nothing written; opted-out: disabled via
+#   global config; skipped: CLI skipped the sync (AGENTCORE_SKIP_INSTALL); failure-suppressed:
+#   failure downgraded on a teardown deploy; failed: the sync failed the deploy.
+DependencySyncOutcome = Literal["synced", "check-only", "opted-out", "skipped", "failure-suppressed", "failed"]
+
+
+@dataclass(frozen=True, slots=True)
+class DependencyChange:
+    name: str
+    section: DependencySection
+    from_: str
+    to: str
+
+
+@dataclass(frozen=True, slots=True)
+class RestoredDependency:
+    name: str
+    section: DependencySection
+    to: str
+
+
+@dataclass(frozen=True, slots=True)
+class SkippedDependency:
+    name: str
+    raw: str
+    reason: str
+
+
+@dataclass(slots=True)
+class DependencySyncResult:
+    outcome: DependencySyncOutcome
+    # Dependency management disabled via global config: nothing written.
+    opted_out: bool
+    # mode="check": plan computed, nothing written or installed.
+    check_only: bool
+    # Project predated pinning (caret ranges on managed deps rewritten).
+    migrated_from_caret: bool
+    # `npm install` ran (manifest changed, or node_modules was missing).
+    reinstalled: bool
+    # Newer-than-CLI managed dep found but downgraded to a warning.
+    skew_warning: bool
+    changes: list[DependencyChange] = field(default_factory=list)
+    restored: list[RestoredDependency] = field(default_factory=list)
+    skipped: list[SkippedDependency] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+    notice: str | None = None

agentcore/lib/errors/__init__.py

@@ -0,0 +1,5 @@
+from agentcore.lib.errors.types import *  # noqa: F403
+from agentcore.lib.errors.types import __all__ as _types_all
+from agentcore.lib.errors.validation import format_path, format_validation_errors, format_zod_errors
+
+__all__ = [*_types_all, "format_path", "format_validation_errors", "format_zod_errors"]

agentcore/lib/errors/types.py

@@ -0,0 +1,352 @@
+"""Typed error hierarchy (port of ``src/lib/errors/types.ts``)."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from typing import Any, ClassVar, Literal
+
+from agentcore.lib.errors.validation import format_validation_errors
+
+ErrorSource = Literal["user", "client", "service", "unknown"]
+
+
+class BaseError(Exception):
+    """Root of the CLI error taxonomy.
+
+    ``error_source`` classifies the failure ("user" | "client" | "service" | "unknown");
+    each subclass declares a ``default_source`` that callers may override.
+    """
+
+    default_source: ClassVar[ErrorSource] = "unknown"
+
+    def __init__(self, message: str, *, error_source: ErrorSource | None = None, cause: BaseException | None = None):
+        super().__init__(message)
+        self.message = message
+        self.error_source: ErrorSource = error_source or self.default_source
+        if cause is not None:
+            self.__cause__ = cause
+
+    @property
+    def name(self) -> str:
+        return type(self).__name__
+
+    @property
+    def cause(self) -> BaseException | None:
+        return self.__cause__
+
+
+def to_error(err: object) -> BaseException:
+    """Coerce an arbitrary raised value into an exception instance."""
+    return err if isinstance(err, BaseException) else Exception(str(err))
+
+
+def _cause_message(cause: object) -> str:
+    return str(cause)
+
+
+# --- User errors ---
+
+
+class NoProjectError(BaseError):
+    default_source = "user"
+
+    def __init__(self, message: str | None = None, **kwargs: Any):
+        super().__init__(message or 'No agentcore project found. Run "agentcore create" first.', **kwargs)
+
+
+class AgentAlreadyExistsError(BaseError):
+    default_source = "user"
+
+    def __init__(self, agent_name: str, **kwargs: Any):
+        super().__init__(f'An agent named "{agent_name}" already exists in the schema.', **kwargs)
+
+
+class AccessDeniedError(BaseError):
+    default_source = "user"
+
+
+class SecretEncryptionError(BaseError):
+    """A secret could not be encrypted before writing to disk (e.g. machine key unavailable)."""
+
+    default_source = "client"
+
+
+class SecretDecryptionError(BaseError):
+    """A stored secret could not be decrypted (missing/changed key or corrupt ciphertext)."""
+
+    default_source = "user"
+
+
+class DependencyCheckError(BaseError):
+    default_source = "user"
+
+    def __init__(self, errors: Iterable[str], **kwargs: Any):
+        super().__init__("\n".join(errors), **kwargs)
+
+
+class ResourceNotFoundError(BaseError):
+    default_source = "user"
+
+
+class JobNotFoundError(BaseError):
+    default_source = "user"
+
+
+class ValidationError(BaseError):
+    default_source = "user"
+
+
+class StaleCdkConstructError(BaseError):
+    """CDK synth rejected keys the CLI writes: the project's bundled construct is older than the CLI."""
+
+    default_source = "user"
+
+    def __init__(self, rejected_keys: Iterable[str], installed_version: str | None, **kwargs: Any):
+        key_list = ", ".join(f'"{k}"' for k in rejected_keys)
+        version_part = f" (currently {installed_version})" if installed_version else ""
+        super().__init__(
+            f"CDK synth rejected {key_list}, which this CLI writes but the project's installed "
+            f"@aws/agentcore-cdk{version_part} does not recognize. If you did not hand-edit "
+            "agentcore.json, the bundled CDK constructs are likely behind the CLI. Run "
+            "`npm update @aws/agentcore-cdk` in agentcore/cdk/, then re-run `agentcore deploy`.",
+            **kwargs,
+        )
+
+
+class CliVersionTooOldError(BaseError):
+    default_source = "user"
+
+
+class DependencySyncError(BaseError):
+    default_source = "client"
+
+
+class AwsCredentialsError(BaseError):
+    """AWS credentials missing/invalid. Carries a short (interactive) and detailed (CLI) message."""
+
+    default_source = "user"
+
+    def __init__(self, short_message: str, detailed_message: str | None = None, **kwargs: Any):
+        super().__init__(detailed_message or short_message, **kwargs)
+        self.short_message = short_message
+
+
+class MissingCredentialsError(BaseError):
+    default_source = "user"
+
+
+class PackagingError(BaseError):
+    default_source = "user"
+
+
+class ArtifactSizeError(PackagingError):
+    def __init__(self, limit_bytes: int, actual_bytes: int, **kwargs: Any):
+        super().__init__(f"Packaged artifact exceeds {limit_bytes} bytes (actual: {actual_bytes}).", **kwargs)
+
+
+class MissingDependencyError(PackagingError):
+    def __init__(self, binary: str, install_hint: str | None = None, **kwargs: Any):
+        super().__init__(
+            f"{binary} is required. {install_hint}" if install_hint else f"{binary} is required.", **kwargs
+        )
+
+
+class MissingProjectFileError(PackagingError):
+    def __init__(self, file_path: str, **kwargs: Any):
+        super().__init__(f"Required project file not found: {file_path}", **kwargs)
+
+
+class UnsupportedLanguageError(PackagingError):
+    def __init__(self, language: str, **kwargs: Any):
+        super().__init__(f"{language} packaging is not supported yet.", **kwargs)
+
+
+# --- Config errors (user) ---
+
+
+class ConfigError(BaseError):
+    """Base class for config-file errors."""
+
+    default_source = "user"
+
+
+class ConfigNotFoundError(ConfigError):
+    def __init__(self, file_path: str, file_type: str):
+        super().__init__(f"{file_type} config file not found at: {file_path}")
+        self.file_path = file_path
+        self.file_type = file_type
+
+
+class ConfigReadError(ConfigError):
+    def __init__(self, file_path: str, cause: object):
+        super().__init__(
+            f"Failed to read config file at {file_path}: {_cause_message(cause)}",
+            cause=cause if isinstance(cause, BaseException) else None,
+        )
+        self.file_path = file_path
+
+
+class ConfigWriteError(ConfigError):
+    def __init__(self, file_path: str, cause: object):
+        super().__init__(
+            f"Failed to write config file at {file_path}: {_cause_message(cause)}",
+            cause=cause if isinstance(cause, BaseException) else None,
+        )
+        self.file_path = file_path
+
+
+class ConfigValidationError(ConfigError):
+    """Schema validation failed.
+
+    ``validation_error`` is a ``pydantic.ValidationError`` or a list of pydantic-style issue
+    dicts (``{"type", "loc", "msg", ...}``).
+    """
+
+    def __init__(self, file_path: str, file_type: str, validation_error: Any):
+        issues = _issues_of(validation_error)
+        super().__init__(f"{file_path}:\n{format_validation_errors(issues)}")
+        self.file_path = file_path
+        self.file_type = file_type
+        self.validation_error = validation_error
+        self.issues = issues
+
+
+def _issues_of(validation_error: Any) -> list[Mapping[str, Any]]:
+    errors = getattr(validation_error, "errors", None)
+    if callable(errors):
+        return list(errors())
+    return list(validation_error or [])
+
+
+class ConfigParseError(ConfigError):
+    def __init__(self, file_path: str, cause: object):
+        super().__init__(
+            f"Failed to parse JSON in config file at {file_path}: {_cause_message(cause)}",
+            cause=cause if isinstance(cause, BaseException) else None,
+        )
+        self.file_path = file_path
+
+
+class GitInitError(BaseError):
+    default_source = "client"
+
+
+# --- Service errors ---
+
+
+class ConflictError(BaseError):
+    default_source = "user"
+
+
+class TimeoutError(BaseError):  # noqa: A001 - mirrors the upstream class name
+    default_source = "service"
+
+
+class DevServerError(BaseError):
+    default_source = "client"
+
+    def __init__(self, status_code: int, body: str, **kwargs: Any):
+        super().__init__(body or f"Server returned {status_code}", **kwargs)
+        self.status_code = status_code
+
+
+class DevServerConnectionError(BaseError):
+    default_source = "client"
+
+
+class ServiceError(BaseError):
+    default_source = "service"
+
+
+class ThrottlingError(BaseError):
+    default_source = "service"
+
+
+class ServiceQuotaError(BaseError):
+    default_source = "service"
+
+
+class PollTimeoutError(BaseError):
+    default_source = "service"
+
+    def __init__(self, timeout_ms: float, **kwargs: Any):
+        super().__init__(f"Polling timed out after {_fmt_num(timeout_ms)}ms", **kwargs)
+
+
+class PollExhaustedError(BaseError):
+    default_source = "service"
+
+    def __init__(self, max_attempts: int, **kwargs: Any):
+        super().__init__(f"Polling exhausted after {max_attempts} attempts", **kwargs)
+
+
+class IngestionError(BaseError):
+    default_source = "service"
+
+
+class ShellKickedError(BaseError):
+    default_source = "service"
+
+    def __init__(self, **kwargs: Any):
+        super().__init__("Shell session was taken over by another client (close code 4000)", **kwargs)
+
+
+class UserCancellationError(BaseError):
+    default_source = "user"
+
+    def __init__(self, **kwargs: Any):
+        super().__init__("User cancelled", **kwargs)
+
+
+class ExportHarnessError(BaseError):
+    default_source = "client"
+
+
+def _fmt_num(value: float) -> str:
+    return str(int(value)) if float(value).is_integer() else str(value)
+
+
+__all__ = [
+    "AccessDeniedError",
+    "AgentAlreadyExistsError",
+    "ArtifactSizeError",
+    "AwsCredentialsError",
+    "BaseError",
+    "CliVersionTooOldError",
+    "ConfigError",
+    "ConfigNotFoundError",
+    "ConfigParseError",
+    "ConfigReadError",
+    "ConfigValidationError",
+    "ConfigWriteError",
+    "ConflictError",
+    "DependencyCheckError",
+    "DependencySyncError",
+    "DevServerConnectionError",
+    "DevServerError",
+    "ErrorSource",
+    "ExportHarnessError",
+    "GitInitError",
+    "IngestionError",
+    "JobNotFoundError",
+    "MissingCredentialsError",
+    "MissingDependencyError",
+    "MissingProjectFileError",
+    "NoProjectError",
+    "PackagingError",
+    "PollExhaustedError",
+    "PollTimeoutError",
+    "ResourceNotFoundError",
+    "SecretDecryptionError",
+    "SecretEncryptionError",
+    "ServiceError",
+    "ServiceQuotaError",
+    "ShellKickedError",
+    "StaleCdkConstructError",
+    "ThrottlingError",
+    "TimeoutError",
+    "UnsupportedLanguageError",
+    "UserCancellationError",
+    "ValidationError",
+    "to_error",
+]