aaws 0.1.0__py3-none-any.whl

aaws/__init__.py

@@ -0,0 +1,3 @@
+"""aaws — AI-assisted AWS CLI."""
+
+__version__ = "0.1.0"

aaws/cli.py

@@ -0,0 +1,290 @@
+"""aaws CLI — entry point for all commands."""
+
+from __future__ import annotations
+
+from typing import Annotated, Optional
+
+import typer
+from rich.console import Console
+
+app = typer.Typer(
+    name="aaws",
+    help="AI-assisted AWS CLI — natural language in, aws command out.",
+    no_args_is_help=True,
+    rich_markup_mode="rich",
+)
+
+config_app = typer.Typer(help="Manage aaws configuration.")
+app.add_typer(config_app, name="config")
+
+console = Console()
+
+
+# ── Helpers ───────────────────────────────────────────────────────────────────
+
+def _resolve_aws_context(
+    profile: str | None,
+    region: str | None,
+    config: object,
+) -> tuple[str, str]:
+    """Return the effective AWS profile and region."""
+    import boto3  # noqa: PLC0415
+
+    aws = getattr(config, "aws", None)
+    effective_profile = profile or getattr(aws, "default_profile", None) or "default"
+
+    if region:
+        effective_region = region
+    elif getattr(aws, "default_region", None):
+        effective_region = aws.default_region  # type: ignore[union-attr]
+    else:
+        try:
+            session = boto3.Session(profile_name=effective_profile)
+            effective_region = session.region_name or "us-east-1"
+        except Exception:
+            effective_region = "us-east-1"
+
+    return effective_profile, effective_region
+
+
+def _load_or_exit() -> object:
+    """Load config or print actionable error and exit."""
+    from .config import load_config  # noqa: PLC0415
+    from .errors import ConfigNotFoundError  # noqa: PLC0415
+
+    try:
+        return load_config()
+    except ConfigNotFoundError:
+        console.print(
+            "[bold red]No configuration found.[/bold red] "
+            "Run [cyan]aaws config init[/cyan] to set up."
+        )
+        raise typer.Exit(1)
+
+
+# ── Root command ──────────────────────────────────────────────────────────────
+
+@app.callback(invoke_without_command=True)
+def main(
+    ctx: typer.Context,
+    request: Annotated[
+        Optional[str], typer.Argument(help="Natural language AWS request")
+    ] = None,
+    profile: Annotated[
+        Optional[str], typer.Option("--profile", "-p", help="AWS profile to use")
+    ] = None,
+    region: Annotated[
+        Optional[str], typer.Option("--region", "-r", help="AWS region to use")
+    ] = None,
+    raw: Annotated[
+        bool, typer.Option("--raw", help="Print raw JSON without formatting")
+    ] = False,
+    dry_run: Annotated[
+        bool, typer.Option("--dry-run", help="Show generated command without executing it")
+    ] = False,
+    accept_responsibility: Annotated[
+        bool,
+        typer.Option(
+            "--i-accept-responsibility",
+            help="Override tier-3 (catastrophic) operation refusal",
+        ),
+    ] = False,
+) -> None:
+    """Translate a natural language request into an AWS CLI command and run it."""
+    if ctx.invoked_subcommand is not None:
+        return
+
+    if request is None:
+        console.print(
+            "Usage: aaws [OPTIONS] REQUEST\n\nRun [cyan]aaws --help[/cyan] for more information."
+        )
+        raise typer.Exit()
+
+    from .errors import AawsError, ProtectedProfileError, TranslationError, handle_error  # noqa: PLC0415
+    from .executor import check_aws_cli, execute  # noqa: PLC0415
+    from .formatter import format_output  # noqa: PLC0415
+    from .providers import get_provider  # noqa: PLC0415
+    from .safety.classifier import apply_safety_gate, classify, was_dry_run_requested  # noqa: PLC0415
+    from .translator import translate  # noqa: PLC0415
+
+    check_aws_cli()
+    config = _load_or_exit()
+    effective_profile, effective_region = _resolve_aws_context(profile, region, config)
+    effective_raw = raw or getattr(getattr(config, "output", None), "raw", False)
+
+    provider = get_provider(config)
+
+    # Translate
+    try:
+        response = translate(request, effective_profile, effective_region, [], provider)
+    except TranslationError as e:
+        console.print(f"[bold red]Translation failed:[/bold red] {e}")
+        raise typer.Exit(1)
+    except AawsError as e:
+        console.print(f"[bold red]Error:[/bold red] {e}")
+        raise typer.Exit(1)
+
+    # Handle clarification
+    if response.clarification:
+        console.print(f"[bold yellow]?[/bold yellow] {response.clarification}")
+        raise typer.Exit()
+
+    tier = classify(response.command, response.risk_tier)
+
+    # Dry-run flag: show command; don't execute
+    if dry_run:
+        console.print(f"\n[bold]Generated command:[/bold] [cyan]{response.command}[/cyan]")
+        console.print(f"[dim]{response.explanation}[/dim]")
+        console.print(f"[dim]Risk tier: {tier}[/dim]")
+        raise typer.Exit()
+
+    # Safety gate
+    try:
+        should_run = apply_safety_gate(
+            response.command,
+            tier,
+            response.explanation,
+            effective_profile,
+            config,
+            accept_responsibility=accept_responsibility,
+        )
+    except ProtectedProfileError as e:
+        console.print(f"[bold red]Blocked:[/bold red] {e}")
+        raise typer.Exit(1)
+
+    if was_dry_run_requested():
+        # User chose --dry-run from the confirmation prompt — re-run with --dry-run appended
+        dry_command = response.command + " --dry-run"
+        console.print(f"\n[bold]Running:[/bold] [cyan]{dry_command}[/cyan]")
+        result = execute(dry_command)
+        if result.success:
+            console.print("[green]Dry run succeeded — no changes were made.[/green]")
+            console.print(result.stdout or "")
+        else:
+            handle_error(dry_command, result, effective_profile, provider)
+        raise typer.Exit()
+
+    if not should_run:
+        console.print("[dim]Cancelled.[/dim]")
+        raise typer.Exit()
+
+    result = execute(response.command)
+    if result.success:
+        format_output(result.stdout, raw=effective_raw)
+    else:
+        handle_error(response.command, result, effective_profile, provider)
+        raise typer.Exit(result.exit_code)
+
+
+# ── explain command ───────────────────────────────────────────────────────────
+
+@app.command("explain")
+def explain_command(
+    command: Annotated[str, typer.Argument(help="AWS CLI command to explain")],
+) -> None:
+    """Explain what an existing AWS CLI command does."""
+    from .errors import AawsError  # noqa: PLC0415
+    from .providers import get_provider  # noqa: PLC0415
+    from .providers.base import Message, TOOL_SCHEMA  # noqa: PLC0415
+
+    config = _load_or_exit()
+    provider = get_provider(config)
+
+    messages = [
+        Message(
+            role="user",
+            content=(
+                f"Explain the following AWS CLI command in plain English. "
+                f"Describe what it does, what each flag means, and any important "
+                f"safety considerations or caveats:\n\n  {command}"
+            ),
+        )
+    ]
+
+    try:
+        response = provider.complete(messages, TOOL_SCHEMA)
+        console.print(f"\n[bold]Command:[/bold] [cyan]{command}[/cyan]\n")
+        console.print(response.explanation or "No explanation available.")
+    except AawsError as e:
+        console.print(f"[bold red]Error:[/bold red] {e}")
+        raise typer.Exit(1)
+
+
+# ── session command ───────────────────────────────────────────────────────────
+
+@app.command("session")
+def session_command(
+    profile: Annotated[
+        Optional[str], typer.Option("--profile", "-p", help="AWS profile to use")
+    ] = None,
+    region: Annotated[
+        Optional[str], typer.Option("--region", "-r", help="AWS region to use")
+    ] = None,
+) -> None:
+    """Start an interactive session with conversation context."""
+    from .executor import check_aws_cli  # noqa: PLC0415
+    from .session import run_session  # noqa: PLC0415
+
+    check_aws_cli()
+    config = _load_or_exit()
+    effective_profile, effective_region = _resolve_aws_context(profile, region, config)
+    run_session(config, effective_profile, effective_region)
+
+
+# ── config commands ───────────────────────────────────────────────────────────
+
+@config_app.command("init")
+def config_init() -> None:
+    """Run the first-time configuration wizard."""
+    from rich.prompt import Confirm, Prompt  # noqa: PLC0415
+
+    from .config import AawsConfig, LLMConfig, write_config  # noqa: PLC0415
+
+    console.print("[bold cyan]aaws configuration wizard[/bold cyan]\n")
+
+    provider_choice = Prompt.ask(
+        "LLM provider",
+        choices=["bedrock", "openai"],
+        default="bedrock",
+    )
+
+    if provider_choice == "bedrock":
+        model = Prompt.ask(
+            "Bedrock model ID",
+            default="anthropic.claude-3-5-haiku-20241022-v1:0",
+        )
+        api_key = None
+    else:
+        model = Prompt.ask("OpenAI model", default="gpt-4o-mini")
+        api_key = Prompt.ask(
+            "OpenAI API key (or set OPENAI_API_KEY env var)",
+            password=True,
+        )
+
+    default_profile = Prompt.ask("Default AWS profile", default="default")
+    default_region = Prompt.ask("Default AWS region", default="us-east-1")
+
+    from .config import AWSConfig  # noqa: PLC0415
+
+    config = AawsConfig(
+        llm=LLMConfig(provider=provider_choice, model=model, api_key=api_key or None),
+        aws=AWSConfig(default_profile=default_profile, default_region=default_region),
+    )
+    path = write_config(config)
+    console.print(f"\n[green]✓[/green] Configuration saved to [cyan]{path}[/cyan]")
+    console.print('Run [cyan]aaws "list my S3 buckets"[/cyan] to test.')
+
+
+@config_app.command("show")
+def config_show() -> None:
+    """Show the resolved effective configuration (secrets masked)."""
+    import json  # noqa: PLC0415
+
+    config = _load_or_exit()
+    data = config.model_dump()  # type: ignore[union-attr]
+
+    # Mask sensitive fields
+    if data.get("llm", {}).get("api_key"):
+        data["llm"]["api_key"] = "***"
+
+    console.print_json(json.dumps(data, indent=2))

aaws/config.py

@@ -0,0 +1,142 @@
+"""Configuration loading, validation, and persistence for aaws."""
+
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path
+from typing import Optional
+
+import yaml
+from platformdirs import user_config_dir
+from pydantic import BaseModel
+
+from .errors import ConfigNotFoundError
+
+
+# ── Pydantic models ────────────────────────────────────────────────────────────
+
+class LLMConfig(BaseModel):
+    provider: str = "bedrock"
+    model: str = "anthropic.claude-3-5-haiku-20241022-v1:0"
+    api_key: Optional[str] = None
+    temperature: float = 0.1
+    timeout: int = 30
+
+
+class AWSConfig(BaseModel):
+    default_profile: Optional[str] = None
+    default_region: Optional[str] = None
+
+
+class SafetyConfig(BaseModel):
+    auto_execute_tier: int = 0
+    protected_profiles: list[str] = []
+
+
+class OutputConfig(BaseModel):
+    format: str = "auto"
+    raw: bool = False
+    color: bool = True
+
+
+class AawsConfig(BaseModel):
+    llm: LLMConfig = LLMConfig()
+    aws: AWSConfig = AWSConfig()
+    safety: SafetyConfig = SafetyConfig()
+    output: OutputConfig = OutputConfig()
+
+
+# ── Env var helpers ───────────────────────────────────────────────────────────
+
+_ENV_VAR_RE = re.compile(r"\$\{([^}]+)\}")
+
+
+def _resolve_env_vars(value: str) -> str:
+    """Resolve ${ENV_VAR} references in a string. Leaves unset vars as-is."""
+
+    def replacer(match: re.Match[str]) -> str:
+        var_name = match.group(1)
+        return os.environ.get(var_name, match.group(0))
+
+    return _ENV_VAR_RE.sub(replacer, value)
+
+
+def _resolve_recursive(obj: object) -> object:
+    """Recursively resolve ${ENV_VAR} in all string values of a nested structure."""
+    if isinstance(obj, str):
+        return _resolve_env_vars(obj)
+    if isinstance(obj, dict):
+        return {k: _resolve_recursive(v) for k, v in obj.items()}
+    if isinstance(obj, list):
+        return [_resolve_recursive(i) for i in obj]
+    return obj
+
+
+# Map from AAWS_ env var → (section, field) in the config dict
+_ENV_OVERRIDES: dict[str, tuple[str, str]] = {
+    "AAWS_LLM_PROVIDER": ("llm", "provider"),
+    "AAWS_LLM_MODEL": ("llm", "model"),
+    "AAWS_LLM_API_KEY": ("llm", "api_key"),
+    "AAWS_LLM_TEMPERATURE": ("llm", "temperature"),
+    "AAWS_LLM_TIMEOUT": ("llm", "timeout"),
+    "AAWS_AWS_PROFILE": ("aws", "default_profile"),
+    "AAWS_AWS_REGION": ("aws", "default_region"),
+    "AAWS_SAFETY_AUTO_EXECUTE_TIER": ("safety", "auto_execute_tier"),
+    "AAWS_OUTPUT_FORMAT": ("output", "format"),
+    "AAWS_OUTPUT_RAW": ("output", "raw"),
+    "AAWS_OUTPUT_COLOR": ("output", "color"),
+}
+
+
+def _apply_env_overrides(config_dict: dict) -> dict:  # type: ignore[type-arg]
+    """Apply AAWS_-prefixed environment variables, overriding file-based config."""
+    for env_key, (section, field) in _ENV_OVERRIDES.items():
+        val = os.environ.get(env_key)
+        if val is not None:
+            if section not in config_dict:
+                config_dict[section] = {}
+            config_dict[section][field] = val
+    return config_dict
+
+
+# ── Path helpers ──────────────────────────────────────────────────────────────
+
+def config_path() -> Path:
+    """Return the OS-appropriate config file path."""
+    return Path(user_config_dir("aaws")) / "config.yaml"
+
+
+# ── Public API ────────────────────────────────────────────────────────────────
+
+def load_config(path: Path | None = None) -> AawsConfig:
+    """
+    Load config from YAML file, resolve ${ENV_VAR} references, apply
+    AAWS_-prefixed env var overrides, and return a validated AawsConfig.
+
+    Raises ConfigNotFoundError if the file does not exist.
+    """
+    resolved_path = path or config_path()
+
+    if not resolved_path.exists():
+        raise ConfigNotFoundError(str(resolved_path))
+
+    with resolved_path.open() as f:
+        raw: dict = yaml.safe_load(f) or {}  # type: ignore[assignment]
+
+    raw = _resolve_recursive(raw)  # type: ignore[assignment]
+    raw = _apply_env_overrides(raw)  # type: ignore[arg-type]
+
+    return AawsConfig.model_validate(raw)
+
+
+def write_config(config: AawsConfig, path: Path | None = None) -> Path:
+    """Serialize config to YAML, creating parent directories as needed."""
+    resolved_path = path or config_path()
+    resolved_path.parent.mkdir(parents=True, exist_ok=True)
+
+    data = config.model_dump(exclude_none=True)
+    with resolved_path.open("w") as f:
+        yaml.dump(data, f, default_flow_style=False, sort_keys=False)
+
+    return resolved_path

aaws/errors.py

@@ -0,0 +1,161 @@
+"""Custom exceptions and error types for aaws."""
+
+from __future__ import annotations
+
+import re
+from enum import Enum, auto
+
+
+class ErrorType(Enum):
+    EXPIRED_TOKEN = auto()
+    NO_CREDENTIALS = auto()
+    ACCESS_DENIED = auto()
+    BUCKET_NOT_EMPTY = auto()
+    NO_SUCH_BUCKET = auto()
+    RESOURCE_NOT_FOUND = auto()
+    RESOURCE_CONFLICT = auto()
+    TIMEOUT = auto()
+    UNKNOWN = auto()
+
+
+class AawsError(Exception):
+    """Base exception for aaws errors."""
+
+
+class TranslationError(AawsError):
+    """Raised when the LLM fails to produce a valid AWS CLI command after retries."""
+
+
+class ProtectedProfileError(AawsError):
+    """Raised when a write operation is attempted against a protected AWS profile."""
+
+    def __init__(self, profile: str) -> None:
+        super().__init__(
+            f"Profile '{profile}' is protected (read-only). Switch profiles to make changes."
+        )
+        self.profile = profile
+
+
+class ConfigNotFoundError(AawsError):
+    """Raised when no aaws config file exists."""
+
+
+# ── Credential / permission pattern matching ──────────────────────────────────
+
+_CREDENTIAL_PATTERNS: list[tuple[re.Pattern[str], str]] = [
+    (
+        re.compile(r"ExpiredTokenException|ExpiredToken|Token.*expired", re.I),
+        "Your AWS session has expired. Refresh it with: aws sso login --profile {profile}",
+    ),
+    (
+        re.compile(r"Unable to locate credentials|NoCredentialsError|no credentials", re.I),
+        "No AWS credentials found. Configure them with: aws configure",
+    ),
+]
+
+_ACCESS_DENIED_RE = re.compile(
+    r"is not authorized to perform:\s*(\S+)", re.I
+)
+
+_RESOURCE_PATTERNS: list[tuple[re.Pattern[str], ErrorType]] = [
+    (re.compile(r"BucketNotEmpty", re.I), ErrorType.BUCKET_NOT_EMPTY),
+    (re.compile(r"NoSuchBucket", re.I), ErrorType.NO_SUCH_BUCKET),
+    (re.compile(r"AccessDeniedException|is not authorized", re.I), ErrorType.ACCESS_DENIED),
+    (
+        re.compile(r"NoSuchKey|NoSuchEntity|does not exist|not found", re.I),
+        ErrorType.RESOURCE_NOT_FOUND,
+    ),
+    (
+        re.compile(r"AlreadyExists|BucketAlreadyOwned|ResourceConflict", re.I),
+        ErrorType.RESOURCE_CONFLICT,
+    ),
+    (
+        re.compile(r"ExpiredTokenException|ExpiredToken|Token.*expired", re.I),
+        ErrorType.EXPIRED_TOKEN,
+    ),
+    (
+        re.compile(r"Unable to locate credentials|NoCredentialsError", re.I),
+        ErrorType.NO_CREDENTIALS,
+    ),
+]
+
+
+def classify_error(stderr: str) -> ErrorType:
+    """Classify an AWS CLI error from stderr content."""
+    for pattern, error_type in _RESOURCE_PATTERNS:
+        if pattern.search(stderr):
+            return error_type
+    return ErrorType.UNKNOWN
+
+
+def get_credential_message(stderr: str, profile: str) -> str | None:
+    """Return a hardcoded actionable message for credential/auth errors, or None."""
+    for pattern, message in _CREDENTIAL_PATTERNS:
+        if pattern.search(stderr):
+            return message.format(profile=profile)
+
+    match = _ACCESS_DENIED_RE.search(stderr)
+    if match:
+        action = match.group(1) if match.lastindex and match.group(1) else "the required action"
+        return (
+            f"Access denied: {action}\n"
+            "Check your IAM permissions or switch to a profile with the required access."
+        )
+
+    return None
+
+
+def interpret_error(command: str, stderr: str, provider: object) -> str:
+    """Use the LLM to interpret a resource error and suggest next steps."""
+    from .providers.base import Message, TOOL_SCHEMA  # noqa: PLC0415
+
+    messages = [
+        Message(
+            role="user",
+            content=(
+                f"The following AWS CLI command failed:\n"
+                f"  {command}\n\n"
+                f"Error output:\n  {stderr.strip()}\n\n"
+                "Explain what went wrong in plain English and suggest the exact command(s) "
+                "needed to fix or work around this issue."
+            ),
+        )
+    ]
+
+    try:
+        response = provider.complete(messages, TOOL_SCHEMA)  # type: ignore[union-attr]
+        return response.explanation or "Unable to interpret error."
+    except Exception:
+        return stderr.strip()
+
+
+def handle_error(command: str, result: object, profile: str, provider: object) -> None:
+    """Route AWS CLI errors to appropriate handler and render for the user."""
+    from rich.console import Console  # noqa: PLC0415
+
+    from .formatter import render_error  # noqa: PLC0415
+
+    console = Console()
+    stderr: str = getattr(result, "stderr", "")
+
+    # Credential/auth errors → hardcoded actionable message (no LLM call)
+    cred_msg = get_credential_message(stderr, profile)
+    if cred_msg:
+        render_error(stderr, suggestion=cred_msg)
+        return
+
+    error_type = classify_error(stderr)
+
+    if error_type in (
+        ErrorType.BUCKET_NOT_EMPTY,
+        ErrorType.NO_SUCH_BUCKET,
+        ErrorType.RESOURCE_NOT_FOUND,
+        ErrorType.RESOURCE_CONFLICT,
+    ):
+        try:
+            interpretation = interpret_error(command, stderr, provider)
+            render_error(stderr, suggestion=interpretation)
+        except Exception:
+            render_error(stderr)
+    else:
+        render_error(stderr)

aaws/executor.py

@@ -0,0 +1,53 @@
+"""Subprocess execution of AWS CLI commands."""
+
+from __future__ import annotations
+
+import shlex
+import shutil
+import subprocess
+import sys
+from dataclasses import dataclass
+
+
+@dataclass
+class ExecutionResult:
+    stdout: str
+    stderr: str
+    exit_code: int
+
+    @property
+    def success(self) -> bool:
+        return self.exit_code == 0
+
+
+def check_aws_cli() -> None:
+    """
+    Verify the aws CLI is present in PATH.
+    Exits with code 1 and an actionable message if not found.
+    """
+    if shutil.which("aws") is None:
+        from rich.console import Console  # noqa: PLC0415
+
+        Console().print(
+            "[bold red]Error:[/bold red] AWS CLI not found in PATH.\n"
+            "Install it from: "
+            "https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html"
+        )
+        sys.exit(1)
+
+
+def execute(command: str) -> ExecutionResult:
+    """
+    Execute an AWS CLI command via subprocess.
+
+    Security: never uses shell=True. The command string is tokenised with
+    shlex.split and passed as a list to subprocess.run, preventing shell
+    injection regardless of what the LLM produced.
+    """
+    tokens = shlex.split(command)
+    result = subprocess.run(tokens, capture_output=True, text=True)
+    return ExecutionResult(
+        stdout=result.stdout,
+        stderr=result.stderr,
+        exit_code=result.returncode,
+    )