agentcore-cli 0.31.1__py3-none-any.whl

agentcore/cli/commands/create/validate.py

@@ -0,0 +1,195 @@
+"""`create` flag validation (port of src/cli/commands/create/validate.ts).
+
+``options`` is a dict keyed by upstream option names; it is normalized in place like upstream.
+"""
+
+import os
+from typing import Any, Final
+
+from agentcore.cli.commands.add._common import ValidationResult, first_issue
+from agentcore.cli.commands.add.validate import apply_lifecycle, session_storage_mount_path_issue
+from agentcore.cli.commands.shared import filesystem_utils as fs
+from agentcore.cli.commands.shared.vpc_utils import validate_vpc_options
+from agentcore.schema import (
+    BUILD_TYPES,
+    MAX_EFS_MOUNTS,
+    MAX_S3_MOUNTS,
+    MODEL_PROVIDERS,
+    PROTOCOL_MODES,
+    SDK_FRAMEWORKS,
+    TARGET_LANGUAGES,
+    AgentName,
+    ProjectName,
+    get_frameworks_for_language,
+    get_supported_frameworks_for_protocol,
+    get_supported_model_providers,
+    is_framework_supported_for_language,
+    match_enum_value,
+    match_sdk_framework,
+)
+from agentcore.templates import apply_template_option_defaults, validate_template_options
+
+MEMORY_OPTIONS: Final = ("none", "shortTerm", "longAndShortTerm")
+
+
+def validate_folder_not_exists(name: str, cwd: str) -> bool | str:
+    if os.path.exists(os.path.join(cwd, name)):
+        return f"A folder named '{name}' already exists in this directory"
+    return True
+
+
+def validate_mount_pairs(options: dict[str, Any]) -> ValidationResult | None:
+    """EFS / S3 Files pair checks shared by the agent and harness create paths."""
+    for arn_key, path_key, label, validator, maximum in (
+        ("efsAccessPointArn", "efsMountPath", "EFS", fs.validate_efs_access_point_arn, MAX_EFS_MOUNTS),
+        ("s3AccessPointArn", "s3MountPath", "S3 Files", fs.validate_s3_files_access_point_arn, MAX_S3_MOUNTS),
+    ):
+        arns, paths = options.get(arn_key) or [], options.get(path_key) or []
+        if not arns and not paths:
+            continue
+        pairs = fs.zip_access_point_pairs(arns, paths, label)
+        if not pairs.success:
+            return ValidationResult(False, pairs.error)
+        check = fs.validate_access_point_mounts(pairs.mounts, validator)
+        if not check.success:
+            return ValidationResult(False, check.error)
+        if len(arns) > maximum:
+            return ValidationResult(False, f"Maximum {maximum} {label} mounts allowed (got {len(arns)})")
+        if options.get("networkMode") != "VPC":
+            return ValidationResult(
+                False,
+                f"{label} filesystem mounts require VPC network mode. Add --network-mode VPC --subnets <ids> "
+                "--security-groups <ids>.",
+            )
+    return None
+
+
+def validate_create_options(options: dict[str, Any], cwd: str | None = None) -> ValidationResult:
+    if not options.get("name") and not (options.get("agent") is False and options.get("projectName")):
+        return ValidationResult(False, "--name is required")
+
+    project_name = options.get("projectName") or options["name"]
+    issue = first_issue(ProjectName, project_name)
+    if issue:
+        return ValidationResult(False, issue)
+
+    folder = validate_folder_not_exists(options.get("directory") or project_name, cwd or os.getcwd())
+    if folder is not True:
+        return ValidationResult(False, folder)  # type: ignore[arg-type]
+
+    if options.get("agent") is False:
+        return ValidationResult(True)
+
+    issue = first_issue(AgentName, options.get("name"))
+    if issue:
+        return ValidationResult(False, issue)
+
+    if options.get("type") == "import":
+        if not options.get("agentId"):
+            return ValidationResult(False, "--agent-id is required for import")
+        if not options.get("agentAliasId"):
+            return ValidationResult(False, "--agent-alias-id is required for import")
+        if not options.get("region"):
+            return ValidationResult(False, "--region is required for import")
+        if not options.get("framework"):
+            return ValidationResult(False, "--framework is required for import (Strands or LangChain_LangGraph)")
+        fw = match_enum_value(SDK_FRAMEWORKS, options["framework"]) or options["framework"]
+        options["framework"] = fw
+        if fw not in ("Strands", "LangChain_LangGraph"):
+            return ValidationResult(False, f"Import only supports Strands or LangChain_LangGraph, got: {fw}")
+        if options.get("memory") is None:
+            options["memory"] = "none"
+        if options["memory"] not in MEMORY_OPTIONS:
+            return ValidationResult(
+                False, f"Invalid memory option: {options['memory']}. Use none, shortTerm, or longAndShortTerm"
+            )
+        return ValidationResult(True)
+
+    for key, values in (("protocol", PROTOCOL_MODES), ("language", TARGET_LANGUAGES)):
+        if options.get(key):
+            options[key] = match_enum_value(values, options[key]) or options[key]
+    if options.get("framework"):
+        options["framework"] = match_sdk_framework(options["framework"]) or options["framework"]
+    for key, values in (("modelProvider", MODEL_PROVIDERS), ("build", BUILD_TYPES)):
+        if options.get(key):
+            options[key] = match_enum_value(values, options[key]) or options[key]
+
+    apply_template_option_defaults(options.get("framework"), options)
+    template_error = validate_template_options(options.get("framework"), options)
+    if template_error:
+        return ValidationResult(False, template_error)
+
+    protocol = "HTTP"
+    if options.get("protocol"):
+        if options["protocol"] not in PROTOCOL_MODES:
+            return ValidationResult(False, f"Invalid protocol: {options['protocol']}. Use HTTP, MCP, A2A, or AGUI")
+        protocol = options["protocol"]
+
+    if options.get("build") and options["build"] not in BUILD_TYPES:
+        return ValidationResult(False, f"Invalid build type: {options['build']}. Use CodeZip or Container")
+
+    if protocol != "HTTP" and options.get("language") == "TypeScript":
+        return ValidationResult(
+            False, f"{protocol} protocol is not yet supported for TypeScript. Use --protocol HTTP or --language Python."
+        )
+
+    if protocol == "MCP":
+        if options.get("framework"):
+            return ValidationResult(False, "--framework is not applicable for MCP protocol")
+        if options.get("modelProvider"):
+            return ValidationResult(False, "--model-provider is not applicable for MCP protocol")
+        if options.get("memory") and options["memory"] != "none":
+            return ValidationResult(False, "--memory is not applicable for MCP protocol")
+        if options.get("language") and options["language"] not in TARGET_LANGUAGES:
+            return ValidationResult(False, f"Invalid language: {options['language']}")
+        return ValidationResult(True)
+
+    if not (options.get("framework") and options.get("modelProvider") and options.get("memory")):
+        return ValidationResult(
+            False, "Use --no-agent for project-only, or provide all: --framework, --model-provider, --memory"
+        )
+
+    language, framework, provider = options.get("language"), options["framework"], options["modelProvider"]
+    if not language:
+        return ValidationResult(False, "--language is required when creating an agent")
+    if language not in TARGET_LANGUAGES:
+        return ValidationResult(False, f"Invalid language: {language}. Use Python or TypeScript")
+    if framework not in SDK_FRAMEWORKS:
+        return ValidationResult(False, f"Invalid framework: {framework}")
+    if protocol != "HTTP" and framework not in get_supported_frameworks_for_protocol(protocol):  # type: ignore[arg-type]
+        return ValidationResult(False, f"{framework} does not support {protocol} protocol")
+    if provider not in MODEL_PROVIDERS:
+        return ValidationResult(False, f"Invalid model provider: {provider}")
+    if language in ("Python", "TypeScript") and not is_framework_supported_for_language(language, framework):  # type: ignore[arg-type]
+        supported = ", ".join(get_frameworks_for_language(language))  # type: ignore[arg-type]
+        return ValidationResult(
+            False, f"Framework {framework} is not yet available for {language}. Supported: {supported}."
+        )
+    if provider not in get_supported_model_providers(framework):  # type: ignore[arg-type]
+        return ValidationResult(False, f"{framework} does not support {provider}")
+    if options["memory"] not in MEMORY_OPTIONS:
+        return ValidationResult(
+            False, f"Invalid memory option: {options['memory']}. Use none, shortTerm, or longAndShortTerm"
+        )
+
+    vpc = validate_vpc_options(options, options.get("build"))
+    if not vpc.valid:
+        return ValidationResult(False, vpc.error)
+
+    if failure := apply_lifecycle(options):
+        return failure
+
+    if language == "TypeScript":
+        if options.get("sessionStorageMountPath"):
+            return ValidationResult(False, "--session-storage-mount-path is not supported for TypeScript agents")
+        if options.get("efsAccessPointArn") or options.get("efsMountPath"):
+            return ValidationResult(False, "--efs-access-point-arn is not supported for TypeScript agents")
+        if options.get("s3AccessPointArn") or options.get("s3MountPath"):
+            return ValidationResult(False, "--s3-access-point-arn is not supported for TypeScript agents")
+
+    if options.get("sessionStorageMountPath"):
+        issue = session_storage_mount_path_issue(options["sessionStorageMountPath"])
+        if issue:
+            return ValidationResult(False, f"--session-storage-mount-path: {issue}")
+
+    return validate_mount_pairs(options) or ValidationResult(True)

agentcore/cli/commands/create/wizard.py

@@ -0,0 +1,127 @@
+"""Interactive `agentcore create`: prompt-based port of tui/screens/create (CreateScreen + useCreateFlow).
+
+Order: existing-project check -> "Project name" -> "What would you like to build?"
+(Harness / Agent / Skip) -> the add-agent wizard (agent) or the harness primitive's wizard (harness)
+-> project scaffolding with step progress -> created summary.
+"""
+
+import os
+
+import typer
+
+from agentcore.cli import interactive
+from agentcore.cli.commands.add._common import first_issue
+from agentcore.cli.commands.create.action import create_project
+from agentcore.cli.commands.create.validate import validate_folder_not_exists
+from agentcore.cli.errors import get_error_message
+from agentcore.lib import APP_DIR, CONFIG_DIR, find_config_root, get_working_directory
+from agentcore.schema import DEFAULT_MODEL_IDS, ProjectName
+
+CREATE_TYPE_CHOICES = (
+    interactive.Choice("Harness (recommended)", "harness", "Managed config-based agent loop, no code required"),
+    interactive.Choice("Agent", "agent", "Start with a template or bring your own code hosted on AgentCore Runtime"),
+    interactive.Choice("Skip", "skip", "I'll add resources later"),
+)
+
+
+def _on_progress(step: str, status: str) -> None:
+    if status == "done":
+        typer.echo(f"\x1b[32m✓\x1b[0m {step}")
+    elif status == "error":
+        typer.echo(f"\x1b[31m✗\x1b[0m {step}")
+
+
+def run_create_wizard() -> None:
+    cwd = get_working_directory()
+    existing = find_config_root(cwd)
+    if existing:
+        typer.echo("A project already exists at this location.", err=True)
+        typer.echo(f"Found: {existing}", err=True)
+        typer.echo("Use add agent to create a new agent in the existing project.", err=True)
+        raise typer.Exit(1)
+
+    typer.echo("Create a new AgentCore project")
+    typer.echo("This will create a directory with your project name.")
+
+    def validate_name(value: str) -> str | None:
+        issue = first_issue(ProjectName, value)
+        if issue:
+            return issue
+        check = validate_folder_not_exists(value, cwd)
+        return None if check is True else check  # type: ignore[return-value]
+
+    project_name = interactive.text("Project name", validate=validate_name)
+    kind = interactive.select("What would you like to build?", list(CREATE_TYPE_CHOICES))
+
+    agent_options = None
+    if kind == "agent":
+        from agentcore.cli.commands.add.agent_wizard import run_add_agent_wizard
+
+        agent_options = run_add_agent_wizard([], project_name, [], os.path.join(cwd, project_name))
+        if agent_options is None:
+            typer.echo("Cancelled.")
+            raise typer.Exit(0)
+
+    result = create_project(project_name, cwd, on_progress=_on_progress)
+    if not result.success:
+        typer.echo("Project creation failed.", err=True)
+        typer.echo(get_error_message(result.error), err=True)
+        raise typer.Exit(1)
+    project_root = result.value["projectPath"]
+    config_base_dir = os.path.join(project_root, CONFIG_DIR)
+
+    try:
+        if agent_options is not None:
+            _add_agent(agent_options, config_base_dir)
+        elif kind == "harness":
+            _add_harness()
+    except typer.Exit:
+        raise
+    except Exception as exc:  # noqa: BLE001
+        typer.echo("Project creation failed.", err=True)
+        typer.echo(get_error_message(exc), err=True)
+        raise typer.Exit(1) from None
+
+    typer.echo("")
+    typer.echo("Created:")
+    typer.echo(f"  {project_name}/")
+    if agent_options is not None:
+        typer.echo(f"    app/{agent_options.name}/  Agent code location")
+    typer.echo("    agentcore/  Config and CDK project")
+    if agent_options is not None and agent_options.type != "byo" and agent_options.protocol != "MCP":
+        typer.echo(
+            f"Model: {DEFAULT_MODEL_IDS.get(agent_options.model_provider, '')} via {agent_options.model_provider}"
+        )
+    if agent_options is not None and agent_options.type == "byo":
+        typer.echo(f"Copy your agent code to {agent_options.code_location} before deploying.")
+        typer.echo(f"Ensure {agent_options.entrypoint} is the entrypoint file in that folder.")
+    typer.echo("")
+    typer.echo("\x1b[32mProject created successfully!\x1b[0m")
+    typer.echo("")
+    typer.echo("To continue, navigate to your new project:")
+    typer.echo(f"  cd {project_name}")
+    typer.echo("  agentcore")
+
+
+def _add_agent(options, config_base_dir: str) -> None:
+    from agentcore.operations.node import setup_node_project
+    from agentcore.primitives.agent import AgentPrimitive
+
+    _on_progress("Add agent to project", "start")
+    result = AgentPrimitive().add(options, config_base_dir)
+    if not result.success:
+        _on_progress("Add agent to project", "error")
+        raise result.error
+    _on_progress("Add agent to project", "done")
+    if options.language == "TypeScript" and options.type == "create":
+        setup_node_project(os.path.join(os.path.dirname(config_base_dir), APP_DIR, options.name))
+        _on_progress("Set up Node environment", "done")
+
+
+def _add_harness() -> None:
+    from agentcore.primitives.registry import all_primitives
+
+    harness = next((p for p in all_primitives() if p.kind == "harness"), None)
+    if harness is None:
+        raise Exception("Harness creation is not available in this build: `add harness` is not ported yet.")
+    harness.add_interactive()

agentcore/cli/commands/dataset.py

@@ -0,0 +1,119 @@
+"""`agentcore dataset download|publish-version|remove-version` (port of commands/dataset/command.tsx).
+
+Dataset content is synced to the service automatically during `agentcore deploy`; the local JSONL
+file is the DRAFT working copy.
+"""
+
+import json
+
+import typer
+
+from agentcore.aws import agentcore_datasets as datasets_api
+from agentcore.cli.commands._jobs_common import require_project
+from agentcore.cli.groups import group
+from agentcore.cli.run_command import run_cli_command
+from agentcore.lib import ConfigIO
+from agentcore.operations.dataset import delete_dataset_version, publish_dataset, pull_dataset, resolve_dataset
+
+dataset_app = group("dataset")
+dataset_app.info.help = "Manage dataset content and versions"
+
+
+def confirm(question: str) -> bool:
+    """readline-style y/N prompt (upstream reads one line from stdin)."""
+    typer.echo(question, nl=False)
+    try:
+        answer = input()
+    except EOFError:
+        answer = ""
+    return answer.lower() == "y"
+
+
+def _json(payload: dict) -> None:
+    typer.echo(json.dumps(payload, separators=(",", ":"), ensure_ascii=False))
+
+
+@dataset_app.command("download", help="Download dataset from service to local file")
+def download(
+    name: str | None = typer.Option(None, "--name", help="Dataset name"),
+    version: str | None = typer.Option(None, "--version", help="Version to pull (default: DRAFT)"),
+    yes: bool = typer.Option(False, "--yes", help="Skip overwrite confirmation"),
+    as_json: bool = typer.Option(False, "--json", help="Output as JSON"),
+) -> None:
+    require_project()
+
+    def run() -> None:
+        resolved = resolve_dataset(name)
+        config_base_dir = ConfigIO().get_config_root()
+        if not yes and not as_json:
+            typer.echo(f"⚠ This will overwrite: {resolved.location}")
+            typer.echo(f"  (pulling {f'version {version}' if version else 'DRAFT'})")
+            if not confirm("? Continue? (y/N) "):
+                typer.echo("Skipped.")
+                return
+        result = pull_dataset(
+            region=resolved.region,
+            dataset_id=resolved.dataset_id,
+            local_file_path=resolved.location,
+            config_base_dir=config_base_dir,
+            version=version,
+        )
+        if as_json:
+            _json({"success": True, **{k: v for k, v in result.items() if v is not None}})
+        else:
+            typer.secho(f"✓ {result['exampleCount']} examples written to {resolved.location}", fg=typer.colors.GREEN)
+            pulled = "DRAFT" if result["version"] == "DRAFT" else f"version {result['version']}"
+            typer.secho(f" Pulled from: {pulled}", dim=True)
+
+    run_cli_command(as_json, run)
+
+
+@dataset_app.command("publish-version", help="Publish DRAFT as a new immutable version")
+def publish_version(
+    name: str | None = typer.Option(None, "--name", help="Dataset name"),
+    as_json: bool = typer.Option(False, "--json", help="Output as JSON"),
+) -> None:
+    require_project()
+
+    def run() -> None:
+        resolved = resolve_dataset(name)
+        info = datasets_api.get_dataset(region=resolved.region, dataset_id=resolved.dataset_id)
+        if info.get("draftStatus") == "UNMODIFIED" and not as_json:
+            typer.echo("⚠ DRAFT has no unpublished changes (draftStatus: UNMODIFIED)")
+            if not confirm("? Publish anyway? (y/N) "):
+                typer.echo("Skipped.")
+                return
+        result = publish_dataset(region=resolved.region, dataset_id=resolved.dataset_id)
+        if as_json:
+            _json({"success": True, **result})
+        else:
+            typer.secho(
+                f"✓ Published version {result['version']} ({result['exampleCount']} examples)", fg=typer.colors.GREEN
+            )
+            typer.secho(f" draftStatus: {result['draftStatus']}", dim=True)
+
+    run_cli_command(as_json, run)
+
+
+@dataset_app.command("remove-version", help="Delete a specific published version")
+def remove_version(
+    version_id: str = typer.Argument(..., metavar="<version-id>", help="Version number to remove"),
+    name: str | None = typer.Option(None, "--name", help="Dataset name"),
+    as_json: bool = typer.Option(False, "--json", help="Output as JSON"),
+) -> None:
+    require_project()
+
+    def run() -> None:
+        resolved = resolve_dataset(name)
+        if not as_json:
+            typer.echo(f'⚠ This will permanently delete version {version_id} of dataset "{resolved.name}".')
+            if not confirm("? Continue? (y/N) "):
+                typer.echo("Skipped.")
+                return
+        delete_dataset_version(region=resolved.region, dataset_id=resolved.dataset_id, version=version_id)
+        if as_json:
+            _json({"success": True, "name": resolved.name, "deletedVersion": version_id})
+        else:
+            typer.secho(f'✓ Deleted version {version_id} of dataset "{resolved.name}"', fg=typer.colors.GREEN)
+
+    run_cli_command(as_json, run)

agentcore/cli/commands/deploy/__init__.py

@@ -0,0 +1,31 @@
+"""`agentcore deploy` (port of src/cli/commands/deploy)."""
+
+import typer
+
+from agentcore.cli.commands.deploy.actions import (
+    ValidatedDeployOptions,
+    compute_harness_version_drift,
+    handle_deploy,
+    run_deploy,
+    run_diff,
+    select_target_stack,
+)
+from agentcore.cli.commands.deploy.types import DeployOptions, DeployResult
+
+__all__ = [
+    "DeployOptions",
+    "DeployResult",
+    "ValidatedDeployOptions",
+    "compute_harness_version_drift",
+    "handle_deploy",
+    "register",
+    "run_deploy",
+    "run_diff",
+    "select_target_stack",
+]
+
+
+def register(app: typer.Typer) -> None:
+    from agentcore.cli.commands.deploy.command import register_deploy
+
+    register_deploy(app)

agentcore/cli/commands/deploy/_guards.py

@@ -0,0 +1,25 @@
+"""``requireProject`` guard (plain-text port of ``tui/guards/project.tsx``)."""
+
+from __future__ import annotations
+
+import os
+
+import typer
+
+from agentcore.lib.schemas.io.path_resolver import find_config_root, get_working_directory
+
+
+def require_project() -> None:
+    cwd = get_working_directory()
+    config_root = find_config_root(cwd)
+    if not config_root:
+        typer.echo("No agentcore project found.")
+        typer.echo("Run agentcore create to fix this.")
+        raise typer.Exit(1)
+    project_root = os.path.realpath(os.path.dirname(config_root))
+    resolved_cwd = os.path.realpath(cwd)
+    if resolved_cwd != project_root:
+        typer.echo("Please run this command from your project root directory.")
+        typer.echo(f"You are in: {resolved_cwd}\nProject root: {project_root}")
+        typer.echo(f"Run cd {project_root} to fix this.")
+        raise typer.Exit(1)