✨ Add CloudFormation-based infrastructure deployment

[sodre]

Summary

This PR migrates zae-limiter from programmatic DynamoDB table creation to CloudFormation-based stack management, making it easier for users to manage and delete infrastructure.

Changes

New Components

• StackManager (): Manages CloudFormation stack lifecycle with auto-detection of local DynamoDB environments
• CLI Module (): Provides infrastructure management commands
  • zae-limiter deploy: Deploy CloudFormation stack
  • zae-limiter delete: Delete CloudFormation stack
  • zae-limiter status: Check stack status
  • zae-limiter cfn-template: Export template for custom deployment

API Updates

• Added create_stack parameter to RateLimiter and SyncRateLimiter
• Deprecated create_table parameter (with deprecation warning)
• Added create_stack() and delete_stack() methods
• Added CloudFormation exceptions: StackCreationError, StackAlreadyExistsError

Documentation

• Updated README.md with CloudFormation deployment instructions
• Updated CLAUDE.md with infrastructure management guide
• Added comprehensive tests (25 passing tests)

Key Features

✅ Auto-Detection: Automatically detects local DynamoDB (via endpoint_url) and skips CloudFormation
✅ Backward Compatible: Existing code continues to work with deprecation warnings
✅ CLI Convenience: Simple commands for infrastructure management
✅ Easy Cleanup: Users can delete entire stack via CloudFormation

Usage Examples

Deploy via CLI (Recommended)

zae-limiter deploy --table-name rate_limits --region us-east-1

Auto-create in code

limiter = RateLimiter(
    table_name="rate_limits",
    create_stack=True,  # Auto-creates CloudFormation stack
)

Local development (auto-detects)

limiter = RateLimiter(
    table_name="rate_limits",
    endpoint_url="http://localhost:8000",
    create_table=True,  # Uses direct table creation
)

Testing

All tests pass:

pytest tests/test_cli.py tests/test_stack_manager.py -v
# 25 passed, 4 skipped

Breaking Changes

None - fully backward compatible with deprecation warnings.

🤖 Generated with Claude Code

[claude]

Code Review

Found 1 issue that needs attention:

Resource Leak in StackManager._get_client()

File: src/zae_limiter/infra/stack_manager.py:61-72

Issue: The _get_client() method creates a new aioboto3 client on every call without caching or proper cleanup. Each client enters the async context manager via __aenter__() but never calls the corresponding __aexit__(), causing resource leaks.

Problem:

1. No client caching - creates a new client on every call
2. Missing __aexit__() calls - resources are never cleaned up
3. Empty close() method - no cleanup mechanism

Reference: The correct pattern is demonstrated in repository.py:34-50

Suggested fix: Cache the client in self._client and implement proper cleanup in close() method, similar to Repository class.

---

Additional notes:

• Also checked for CLAUDE.md compliance - no violations found
• The one-line docstrings for sync wrapper methods follow the existing codebase pattern