✨ Add get_status() method for comprehensive status reporting

[sodre]

Summary

• Add Status dataclass with comprehensive status information
• Add get_status() method to RateLimiter and SyncRateLimiter classes
• Enhance CLI status command with rich formatted output showing all status fields

Changes

New Status Dataclass

The Status dataclass consolidates connectivity, infrastructure, identity, versions, and table metrics:

@dataclass
class Status:
    # Connectivity
    available: bool
    latency_ms: float | None

    # Infrastructure
    stack_status: str | None
    table_status: str | None
    aggregator_enabled: bool

    # Identity
    name: str
    region: str | None

    # Versions
    schema_version: str | None
    lambda_version: str | None
    client_version: str

    # Table metrics
    table_item_count: int | None
    table_size_bytes: int | None

New Methods

RateLimiter.get_status() (async):

status = await limiter.get_status()
if status.available and status.stack_status == "CREATE_COMPLETE":
    print(f"Ready! Latency: {status.latency_ms}ms")
    print(f"Schema: {status.schema_version}")
else:
    print("Not ready")

SyncRateLimiter.get_status() (sync):

status = limiter.get_status()

Enhanced CLI Output

The zae-limiter status command now shows rich formatted output:

Status: ZAEL-my-app
==================================================

Connectivity
  Available:     ✓ Yes
  Latency:       15ms
  Region:        us-east-1

Infrastructure
  Stack:         CREATE_COMPLETE
  Table:         ACTIVE
  Aggregator:    Enabled

Versions
  Client:        0.1.0
  Schema:        1.0.0
  Lambda:        0.1.0

Table Metrics
  Items:         ~1,234
  Size:          ~512 KB

✓ Infrastructure is ready

Test plan

• Unit tests for RateLimiter.get_status() covering various states
• Unit tests for SyncRateLimiter.get_status() matching async behavior
• Unit tests for CLI status command with mocked responses
• All 448 unit tests pass
• Linting (ruff) passes
• Type checking (mypy) passes

Closes #115

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 90.30303% with 16 lines in your changes missing coverage. Please review.
✅ Project coverage is 88.15%. Comparing base (68a7381) to head (7e83ffd).
⚠️ Report is 2 commits behind head on main.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
src/zae_limiter/cli.py	88.99%	12 Missing ⚠️
src/zae_limiter/limiter.py	90.47%	4 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #141      +/-   ##
==========================================
+ Coverage   87.64%   88.15%   +0.51%     
==========================================
  Files          19       19              
  Lines        2016     2162     +146     
==========================================
+ Hits         1767     1906     +139     
- Misses        249      256       +7     

Flag	Coverage Δ
e2e	56.01% <81.21%> (+3.13%)	⬆️
integration	61.42% <81.21%> (+2.59%)	⬆️
unit	87.00% <90.30%> (+0.84%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[claude]

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.

[claude]

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.

[github-actions]

⚠️ Performance Alert ⚠️

Possible performance regression was detected for benchmark.
Benchmark result of this commit is worse than the previous benchmark result exceeding threshold 1.30.

Benchmark suite	Current: 7e83ffd	Previous: 68a7381	Ratio
tests/benchmark/test_operations.py::TestCascadeOverheadBenchmarks::test_acquire_with_cascade	32.62154801721996 iter/sec (stddev: 0.03942879027594723)	137.69645669844323 iter/sec (stddev: 0.0003761862040854996)	4.22

This comment was automatically generated by workflow using github-action-benchmark.

[sodre]

This should have been a property, not a getter. Also would ti be possible for the CLI to invoke limiter.stack_status() instead what it is doing? What are the tradeoffs?

[sodre]

Thanks for the feedback! A few considerations:

Property vs Method

For async operations, a property isn't straightforward because properties can't be awaited. We have a few options:

1. Keep as async method (await limiter.get_stack_status()) - Current approach, explicit about async nature
2. Cached property with lazy load - Would require caching the status, which might be stale
3. Sync property that calls asyncio.run internally - Would block and doesn't work well in existing async contexts

Given that stack_status involves a CloudFormation API call (network I/O), making it an async method feels appropriate. The get_ prefix is consistent with other query methods in the class.

However, if you prefer, I could rename it to just stack_status() (dropping the get_ prefix) while keeping it as an async method.

CLI using limiter.stack_status

The current CLI uses StackManager directly, which is lighter since it doesn't set up the DynamoDB connection.

Trade-offs of using RateLimiter in CLI:

• Pro: Single source of truth, true API/CLI parity
• Con: Creates unnecessary DynamoDB session context just to check CloudFormation status

If we keep the current approach (CLI uses StackManager directly), they're still semantically equivalent - both call manager.get_stack_status() under the hood.

What's your preference?

1. Keep get_stack_status() method as-is
2. Rename to stack_status() method (drop get_ prefix)
3. Something else?

[sodre]

Thanks for the feedback! A few considerations:

Property vs Method

For async operations, a property isn't straightforward because properties can't be awaited. We have a few options:

1. Keep as async method (await limiter.get_stack_status()) - Current approach, explicit about async nature
2. Cached property with lazy load - Would require caching the status, which might be stale
3. Sync property that calls asyncio.run internally - Would block and doesn't work well in existing async contexts

Given that stack_status involves a CloudFormation API call (network I/O), making it an async method feels appropriate. The get_ prefix is consistent with other query methods in the class.

However, if you prefer, I could rename it to just stack_status() (dropping the get_ prefix) while keeping it as an async method.

Keep get_stack_status.

CLI using limiter.stack_status

The current CLI uses StackManager directly, which is lighter since it doesn't set up the DynamoDB connection.

Trade-offs of using RateLimiter in CLI:

• Pro: Single source of truth, true API/CLI parity
• Con: Creates unnecessary DynamoDB session context just to check CloudFormation status

If we keep the current approach (CLI uses StackManager directly), they're still semantically equivalent - both call manager.get_stack_status() under the hood.

What's your preference?

Let the CLI use StackManager on its own.