lambda-forge-cli-aws 1.0.0__py3-none-any.whl

lambdaforge/spec_generator.py

@@ -0,0 +1,171 @@
+"""Spec generator — creates .kiro/specs/ files using Amazon Bedrock."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from lambdaforge.bedrock_client import BedrockClient
+
+
+class SpecGenerator:
+    """Generates Kiro-compatible spec files for Lambda projects.
+
+    Uses Amazon Bedrock with Claude Sonnet 4.5 to generate
+    context-aware specs based on the template configuration.
+    """
+
+    SYSTEM_PROMPT = """Eres un AWS Solutions Architect documentando una Lambda recién creada.
+
+Recibes la configuración de la Lambda (runtime, triggers, databases, auth).
+Tu trabajo es generar 4 archivos markdown en español que Kiro pueda usar como specs.
+
+Output esperado (4 secciones separadas por '---SECTION---'):
+
+SECTION 1: overview.md
+- Título H1 con nombre del proyecto
+- 1 párrafo describiendo QUÉ hace
+- 1 párrafo describiendo POR QUÉ existe
+- Lista de "Acceptance Criteria" iniciales
+
+SECTION 2: api-design.md
+- Solo si trigger es api-gateway
+- Endpoints REST con method, path, description
+- Request schema (JSON example)
+- Response schema (JSON example)
+- Status codes
+
+SECTION 3: data-model.md
+- Solo si database es dynamodb
+- Tabla principal con partition key, sort key
+- GSI/LSI si aplica
+- Access patterns (cómo se consulta)
+
+SECTION 4: acceptance-criteria.md
+- 5-10 criterios testeable
+- Formato: - [ ] descripción binaria (pass/fail)
+- Cubren: happy path, errores, validaciones, performance
+
+Reglas críticas:
+- Escribe TODO en español
+- Sé específico y accionable
+- NO inventes endpoints que no estén en el template
+- Acceptance criteria deben ser BINARIOS
+- Usa formato markdown limpio (sin HTML)
+- NO incluyas '```markdown' ni otros code fences (esos se añaden al escribir)"""
+
+    def __init__(
+        self,
+        region: str = "us-east-1",
+        budget_usd: float = 0.50,
+        model_id: str | None = None,
+    ) -> None:
+        self.client = BedrockClient(region=region, model_id=model_id or BedrockClient.DEFAULT_MODEL)
+        self.budget_usd = budget_usd
+        self.total_cost = 0.0
+
+    def generate_all(
+        self,
+        project_path: Path,
+        template_name: str,
+        context: dict,
+    ) -> dict[str, str]:
+        """Generate all spec files for a Lambda project.
+
+        Args:
+            project_path: Path to the generated project
+            template_name: Template used
+            context: Template context variables
+
+        Returns:
+            Dict of {filename: content}
+        """
+        specs_dir = project_path / ".kiro" / "specs"
+        specs_dir.mkdir(parents=True, exist_ok=True)
+
+        # Build user message
+        user_message = f"""Genera las specs para esta Lambda:
+
+Nombre: {context.get("project_name")}
+Template: {template_name}
+Runtime: {context.get("runtime", "python3.12")}
+Trigger: {context.get("trigger", "api-gateway")}
+Database: {context.get("database", "none")}
+Auth: {context.get("auth", "none")}
+Observability: {context.get("observability", "xray")}
+Region: {context.get("aws_region", "us-east-1")}
+Memory: {context.get("memory_mb", 512)}MB
+Timeout: {context.get("timeout_seconds", 30)}s
+
+Genera las 4 secciones separadas por '---SECTION---'."""
+
+        # Check budget
+        if self.total_cost >= self.budget_usd:
+            return {"error": "Budget exhausted, skipping specs generation"}
+
+        # Call Bedrock
+        try:
+            response = self.client.generate(
+                system_prompt=self.SYSTEM_PROMPT,
+                user_message=user_message,
+                max_tokens=3000,
+                temperature=0.4,
+            )
+            # Rough cost estimate
+            self.total_cost += 0.05  # ~5 cents per call typical
+
+        except Exception as e:
+            return {"error": str(e)}
+
+        # Parse sections
+        sections = self._parse_sections(response)
+
+        # Write files
+        written: dict[str, str] = {}
+        for filename, content in sections.items():
+            if content and self._is_relevant(filename, context):
+                filepath = specs_dir / filename
+                filepath.write_text(content, encoding="utf-8")
+                written[filename] = content
+
+        return written
+
+    def _parse_sections(self, response: str) -> dict[str, str]:
+        """Parse the response into sections."""
+        sections = {
+            "overview.md": "",
+            "api-design.md": "",
+            "data-model.md": "",
+            "acceptance-criteria.md": "",
+        }
+
+        # Split by SECTION marker (supports: ---SECTION---, ---SECTION 1:, etc.)
+        parts = re.split(r"---\s*SECTION\s*\d*\s*[:.]?\s*---?\s*", response)
+
+        if len(parts) >= 5:  # 4 sections + preamble
+            sections["overview.md"] = parts[1].strip()
+            sections["api-design.md"] = parts[2].strip()
+            sections["data-model.md"] = parts[3].strip()
+            sections["acceptance-criteria.md"] = parts[4].strip()
+        elif len(parts) >= 4:
+            sections["overview.md"] = parts[1].strip()
+            sections["api-design.md"] = parts[2].strip()
+            sections["data-model.md"] = parts[3].strip()
+        elif len(parts) >= 3:
+            sections["overview.md"] = parts[1].strip()
+            sections["api-design.md"] = parts[2].strip()
+        elif len(parts) >= 2:
+            sections["overview.md"] = parts[1].strip()
+        else:
+            # No markers found — treat entire response as overview
+            sections["overview.md"] = response.strip()
+
+        return sections
+
+    def _is_relevant(self, filename: str, context: dict) -> bool:
+        """Check if a spec file is relevant to the configuration."""
+        if filename == "api-design.md":
+            return context.get("trigger") == "api-gateway"
+        if filename == "data-model.md":
+            return context.get("database") == "dynamodb"
+        return True

lambdaforge/status.py

@@ -0,0 +1,111 @@
+"""Status command — shows the current deployment state of a Lambda project."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+from pathlib import Path
+from typing import Any
+
+from rich.console import Console
+from rich.panel import Panel
+
+console = Console()
+
+
+def show_status(project_path: Path, env: str = "dev") -> None:
+    """Show the deployment status of a Lambda project.
+
+    Queries CloudFormation for the stack status and outputs.
+
+    Args:
+        project_path: Path to the Lambda project
+        env: Target environment
+    """
+    project_name = project_path.name.replace("_", "-")
+    stack_name = f"{project_name}-{env}"
+
+    stack_info = _get_stack_info(stack_name)
+
+    if stack_info is None:
+        console.print(
+            Panel(
+                f"[yellow]Stack '{stack_name}' not found.[/yellow]\n\n"
+                f"Not deployed to '{env}' yet.\n"
+                f"Run: [bold]lambdaforge deploy --env {env}[/bold]",
+                title=f"[bold]{project_name}[/bold]",
+                border_style="yellow",
+            )
+        )
+        return
+
+    status = stack_info.get("StackStatus", "UNKNOWN")
+    status_color = _status_color(status)
+
+    outputs = stack_info.get("Outputs", [])
+    outputs_dict = {o["OutputKey"]: o["OutputValue"] for o in outputs}
+
+    lines = [
+        f"[bold]Stack:[/bold] {stack_name}",
+        f"[bold]Status:[/bold] [{status_color}]{status}[/{status_color}]",
+        f"[bold]Environment:[/bold] {env}",
+    ]
+
+    if "Description" in stack_info:
+        lines.append(f"[bold]Description:[/bold] {stack_info['Description']}")
+
+    updated = stack_info.get("LastUpdatedTime", stack_info.get("CreationTime", ""))
+    if updated:
+        lines.append(f"[bold]Last deployed:[/bold] {updated}")
+
+    if outputs_dict:
+        lines.append("")
+        lines.append("[bold]Outputs:[/bold]")
+        for key, value in outputs_dict.items():
+            lines.append(f"  {key}: [cyan]{value}[/cyan]")
+
+    tags = stack_info.get("Tags", [])
+    if tags:
+        lines.append("")
+        lines.append("[bold]Tags:[/bold]")
+        for tag in tags:
+            lines.append(f"  {tag['Key']}: {tag['Value']}")
+
+    console.print(
+        Panel("\n".join(lines), title=f"[bold]{project_name}[/bold]", border_style=status_color)
+    )
+
+
+def _get_stack_info(stack_name: str) -> dict[str, Any] | None:
+    """Query CloudFormation for stack information."""
+    try:
+        result = subprocess.run(
+            [
+                "aws",
+                "cloudformation",
+                "describe-stacks",
+                "--stack-name",
+                stack_name,
+                "--output",
+                "json",
+            ],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        data = json.loads(result.stdout)
+        stacks = data.get("Stacks", [])
+        return stacks[0] if stacks else None
+    except (subprocess.CalledProcessError, json.JSONDecodeError, FileNotFoundError):
+        return None
+
+
+def _status_color(status: str) -> str:
+    """Map CloudFormation status to a Rich color."""
+    if "COMPLETE" in status and "DELETE" not in status:
+        return "green"
+    elif "IN_PROGRESS" in status:
+        return "yellow"
+    elif "FAILED" in status or "DELETE" in status:
+        return "red"
+    return "dim"

lambdaforge/templates.py

@@ -0,0 +1,106 @@
+"""Template catalog — defines all available Lambda templates."""
+
+from __future__ import annotations
+
+from typing import Any
+
+TEMPLATES: dict[str, dict[str, Any]] = {
+    "python-api": {
+        "description": "Lambda triggered by API Gateway with Python 3.12",
+        "runtime": "python3.12",
+        "triggers": ["api-gateway", "alb", "function-url"],
+        "features": [
+            "cors",
+            "auth-cognito",
+            "request-validation",
+            "error-handler",
+            "structured-logging",
+            "xray-tracing",
+        ],
+        "dependencies": [
+            "pydantic>=2.5.0",
+            "aws-lambda-powertools>=2.30.0",
+            "aws-xray-sdk>=2.12.0",
+        ],
+        "default_memory": 512,
+        "default_timeout": 30,
+    },
+    "python-cron": {
+        "description": "Lambda triggered by EventBridge schedule (cron job)",
+        "runtime": "python3.12",
+        "triggers": ["eventbridge-schedule"],
+        "features": [
+            "retry-config",
+            "dlq",
+            "structured-logging",
+            "xray-tracing",
+            "timeout-config",
+        ],
+        "dependencies": [
+            "aws-lambda-powertools>=2.30.0",
+            "boto3>=1.34.0",
+        ],
+        "default_memory": 512,
+        "default_timeout": 300,
+    },
+    "python-queue": {
+        "description": "Lambda triggered by SQS queue (with DLQ + batch)",
+        "runtime": "python3.12",
+        "triggers": ["sqs", "sns"],
+        "features": [
+            "batch-processing",
+            "partial-batch-response",
+            "dlq",
+            "idempotency",
+            "xray-tracing",
+        ],
+        "dependencies": [
+            "aws-lambda-powertools>=2.30.0",
+        ],
+        "default_memory": 1024,
+        "default_timeout": 60,
+    },
+    "python-stream": {
+        "description": "Lambda triggered by Kinesis or DynamoDB Streams",
+        "runtime": "python3.12",
+        "triggers": ["kinesis", "dynamodb-streams"],
+        "features": [
+            "checkpointing",
+            "iterator-age-alarm",
+            "dlq",
+            "xray-tracing",
+        ],
+        "dependencies": [
+            "aws-lambda-powertools>=2.30.0",
+        ],
+        "default_memory": 1024,
+        "default_timeout": 60,
+    },
+    "python-s3": {
+        "description": "Lambda triggered by S3 events (file processing)",
+        "runtime": "python3.12",
+        "triggers": ["s3"],
+        "features": [
+            "event-filtering",
+            "large-file-handling",
+            "multipart-download",
+            "xray-tracing",
+        ],
+        "dependencies": [
+            "boto3>=1.34.0",
+            "smart-open>=6.4.0",
+        ],
+        "default_memory": 1024,
+        "default_timeout": 120,
+    },
+}
+
+
+def get_template(name: str) -> dict[str, Any] | None:
+    """Get a template by name."""
+    return TEMPLATES.get(name)
+
+
+def list_template_names() -> list[str]:
+    """List all available template names."""
+    return list(TEMPLATES.keys())

lambdaforge/upgrade.py

@@ -0,0 +1,231 @@
+"""Upgrade mode — adds LambdaForge best practices to existing Lambdas."""
+
+from __future__ import annotations
+
+import shutil
+from datetime import datetime
+from pathlib import Path
+
+from rich.console import Console
+from rich.panel import Panel
+
+from lambdaforge.spec_generator import SpecGenerator
+
+console = Console()
+
+
+def upgrade_lambda(project_path: Path) -> None:
+    """Upgrade an existing Lambda with LambdaForge best practices.
+
+    Args:
+        project_path: Path to the Lambda project
+    """
+    console.print(
+        Panel(
+            f"[bold cyan]Upgrading: {project_path}[/bold cyan]",
+            title="[bold]🔥 LambdaForge Upgrade[/bold]",
+        )
+    )
+
+    # 1. Create backup
+    backup_dir = project_path / ".lambdaforge-backup" / datetime.now().strftime("%Y%m%d-%H%M%S")
+    console.print(f"[dim]Creating backup at {backup_dir}...[/dim]")
+    _backup_project(project_path, backup_dir)
+
+    # 2. Detect what's missing
+    missing = _detect_missing(project_path)
+    console.print(f"[dim]Detected missing features: {', '.join(missing)}[/dim]")
+
+    # 3. Add what's missing
+    if "xray" in missing:
+        console.print("[dim]Adding X-Ray tracing...[/dim]")
+        _add_xray(project_path)
+
+    if "structured-logging" in missing:
+        console.print("[dim]Adding structured logging...[/dim]")
+        _add_structured_logging(project_path)
+
+    if "tests" in missing:
+        console.print("[dim]Adding basic tests...[/dim]")
+        _add_basic_tests(project_path)
+
+    if ".kiro/specs/" in missing or "specs" in missing:
+        console.print("[dim]Generating .kiro/specs/ via Bedrock...[/dim]")
+        try:
+            spec_gen = SpecGenerator()
+            spec_gen.generate_all(
+                project_path=project_path,
+                template_name="upgraded",
+                context={
+                    "project_name": project_path.name,
+                    "runtime": "python3.12",
+                    "trigger": "unknown",
+                    "database": "none",
+                    "auth": "none",
+                    "observability": "xray",
+                    "aws_region": "us-east-1",
+                },
+            )
+            console.print("[green]✓ Specs generated[/green]")
+        except Exception as e:
+            console.print(f"[yellow]⚠ Specs generation failed: {e}[/yellow]")
+
+    # 4. Add CI/CD if missing
+    if "github-actions" in missing:
+        console.print("[dim]Adding GitHub Actions...[/dim]")
+        _add_github_actions(project_path)
+
+    console.print(
+        Panel(
+            f"[bold green]✓ Upgrade complete[/bold green]\n\n"
+            f"Backup: {backup_dir}\n"
+            f"Review changes with: git diff",
+            title="[bold]Done[/bold]",
+            border_style="green",
+        )
+    )
+
+
+def _backup_project(project_path: Path, backup_dir: Path) -> None:
+    """Create a backup of the project before upgrade."""
+    backup_dir.mkdir(parents=True, exist_ok=True)
+    for item in project_path.iterdir():
+        if item.name.startswith(".lambdaforge-backup"):
+            continue
+        if item.is_file():
+            shutil.copy2(item, backup_dir / item.name)
+        elif item.is_dir():
+            shutil.copytree(item, backup_dir / item.name, dirs_exist_ok=True)
+
+
+def _detect_missing(project_path: Path) -> list[str]:
+    """Detect what features are missing from the project."""
+    missing = []
+
+    # Check X-Ray
+    handler_files = list(project_path.glob("**/handler.py")) + list(
+        project_path.glob("**/lambda_function.py")
+    )
+    has_xray = any("@xray_recorder" in f.read_text() for f in handler_files if f.exists())
+    if not has_xray:
+        missing.append("xray")
+
+    # Check structured logging
+    has_logging = any("logger" in f.name.lower() for f in project_path.rglob("*.py"))
+    if not has_logging:
+        missing.append("structured-logging")
+
+    # Check tests
+    has_tests = (project_path / "tests").exists() and any(project_path.glob("tests/test_*.py"))
+    if not has_tests:
+        missing.append("tests")
+
+    # Check .kiro/specs/
+    specs_dir = project_path / ".kiro" / "specs"
+    if not specs_dir.exists() or not any(specs_dir.glob("*.md")):
+        missing.append(".kiro/specs/")
+
+    # Check GitHub Actions
+    gh_actions = project_path / ".github" / "workflows"
+    if not gh_actions.exists() or not any(gh_actions.glob("*.yml")):
+        missing.append("github-actions")
+
+    return missing
+
+
+def _add_xray(project_path: Path) -> None:
+    """Add X-Ray tracing to handler files."""
+    # Add to requirements.txt
+    req_file = project_path / "requirements.txt"
+    if req_file.exists():
+        content = req_file.read_text()
+        if "aws-xray-sdk" not in content:
+            with req_file.open("a") as f:
+                f.write("\n# LambdaForge: X-Ray tracing\naws-xray-sdk>=2.12.0\n")
+
+    # Add decorator to handler
+    for handler in project_path.glob("**/handler.py"):
+        if handler.exists():
+            content = handler.read_text()
+            if "@xray_recorder.capture" not in content:
+                # Add import at top
+                content = "from aws_xray_sdk.core import xray_recorder\n" + content
+                handler.write_text(content)
+
+
+def _add_structured_logging(project_path: Path) -> None:
+    """Add a basic logger module."""
+    utils_dir = project_path / "src" / "utils"
+    if not utils_dir.exists():
+        utils_dir.mkdir(parents=True, exist_ok=True)
+
+    logger_file = utils_dir / "logger.py"
+    if not logger_file.exists():
+        logger_file.write_text(
+            '"""Structured logger for the Lambda."""\n'
+            "import logging\n"
+            "import json\n\n\n"
+            "logger = logging.getLogger()\n"
+            "logger.setLevel(logging.INFO)\n\n\n"
+            "def log_event(event_type: str, **kwargs):\n"
+            '    """Log a structured event."""\n'
+            '    payload = {"type": event_type, **kwargs}\n'
+            "    logger.info(json.dumps(payload))\n"
+        )
+
+
+def _add_basic_tests(project_path: Path) -> None:
+    """Add a basic test file."""
+    tests_dir = project_path / "tests"
+    tests_dir.mkdir(exist_ok=True)
+
+    test_file = tests_dir / "test_handler.py"
+    if not test_file.exists():
+        test_file.write_text(
+            '"""Basic tests for the Lambda handler."""\n'
+            "import json\n"
+            "from src.handler import main\n\n\n"
+            "def test_handler_returns_200():\n"
+            '    event = {"httpMethod": "GET", "path": "/"}\n'
+            "    context = {}\n"
+            "    response = main(event, context)\n"
+            '    assert response["statusCode"] == 200\n'
+        )
+
+    # Add pytest config
+    pytest_ini = project_path / "pytest.ini"
+    if not pytest_ini.exists():
+        pytest_ini.write_text(
+            "[pytest]\n"
+            "testpaths = tests\n"
+            "python_files = test_*.py\n"
+            "python_classes = Test*\n"
+            "python_functions = test_*\n"
+        )
+
+
+def _add_github_actions(project_path: Path) -> None:
+    """Add a basic GitHub Actions workflow."""
+    workflows_dir = project_path / ".github" / "workflows"
+    workflows_dir.mkdir(parents=True, exist_ok=True)
+
+    workflow_file = workflows_dir / "ci.yml"
+    if not workflow_file.exists():
+        workflow_file.write_text(
+            "name: CI\n\n"
+            "on:\n"
+            "  push:\n"
+            "    branches: [main]\n"
+            "  pull_request:\n"
+            "    branches: [main]\n\n"
+            "jobs:\n"
+            "  test:\n"
+            "    runs-on: ubuntu-latest\n"
+            "    steps:\n"
+            "      - uses: actions/checkout@v4\n"
+            "      - uses: actions/setup-python@v5\n"
+            "        with:\n"
+            "          python-version: '3.12'\n"
+            "      - run: pip install -r requirements.txt\n"
+            "      - run: pytest\n"
+        )

templates/python-api/cookiecutter.json

@@ -0,0 +1,12 @@
+{
+  "project_name": "my-lambda",
+  "project_slug": "{{ cookiecutter.project_name|replace('-', '_') }}",
+  "module_name": "{{ cookiecutter.project_slug }}",
+  "description": "Serverless API built with AWS Lambda",
+  "author_name": "LambdaForge User",
+  "author_email": "user@example.com",
+  "runtime": "python3.12",
+  "aws_region": "us-east-1",
+  "memory_mb": 512,
+  "timeout_seconds": 30
+}

templates/python-api/{{cookiecutter.project_slug}}/.github/workflows/dependabot.yml

@@ -0,0 +1,22 @@
+{% raw %}
+name: Dependabot
+
+on:
+  pull_request:
+  push:
+
+jobs:
+  dependabot:
+    runs-on: ubuntu-latest
+    if: github.actor == 'dependabot[bot]'
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Approve Dependabot PR
+        run: |
+          gh pr review --approve "$PR_URL"
+          gh pr merge --auto --squash "$PR_URL"
+        env:
+          PR_URL: ${{ github.event.pull_request.html_url }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+{% endraw %}