✨ Support period suffix in CLI -l flag syntax

[sodre]

Problem or Use Case

The CLI -l flag only supports per-minute limits with name:capacity syntax (e.g., -l tpm:10000). Users who need per-second, per-hour, or per-day limits must use the Python API directly — there is no way to express non-minute periods through the CLI. This forces a round trip to code for what should be a simple administrative operation.

Proposed Solution

Extend the -l flag to accept an optional /period suffix: name:rate[/period][:burst]. Period defaults to /min when omitted, preserving full backward compatibility.

Supported period syntax

Suffix	Period	Example
/sec	1 second	-l rps:50/sec
/min	1 minute (default)	-l rpm:1000 or -l rpm:1000/min
/hour	1 hour	-l tph:100000/hour
/day	1 day	-l rpd:1000000/day
/Nunit	N × unit	-l rpm:100/5min (= 300 seconds)

With burst

Burst remains the third colon-separated field, after the rate/period component:

-l tph:100000/hour:150000   # 100k/hour sustained, 150k burst ceiling
-l tpm:10000:15000          # 10k/min sustained, 15k burst (no explicit period)

New helper functions

• _parse_period(period_str) — parses 5min, hour, 2day into seconds
• _format_period(seconds) — formats seconds back to the most natural unit suffix
• _parse_limit() — updated to split rate from period suffix before parsing
• _format_limit() — updated to display refill_amount with period suffix, and (burst: N) when capacity differs from refill_amount

Display format

tpm: 10,000/min
rps: 50/sec
tph: 100,000/hour
rpd: 1,000,000/day
rpm: 100/5min
tpm: 10,000/min (burst: 15,000)

Affected CLI commands

All commands that accept the -l flag are updated with the new help text and examples:

• zae-limiter resource set-defaults
• zae-limiter system set-defaults
• zae-limiter entity set-limits

Acceptance Criteria

• _parse_limit("rps:50/sec") returns a Limit with refill_period_seconds=1 and refill_amount=50
• _parse_limit("tph:100000/hour") returns a Limit with refill_period_seconds=3600
• _parse_limit("rpd:1000000/day") returns a Limit with refill_period_seconds=86400
• _parse_limit("tpm:10000/min") is equivalent to _parse_limit("tpm:10000") (backward compatible)
• _parse_limit("rpm:100/5min") returns refill_period_seconds=300 (multiplied periods)
• _parse_limit("tph:100000/hour:150000") sets capacity=150000 and refill_amount=100000 (burst with period)
• _parse_limit("rpm:100/week") raises click.BadParameter with "Invalid period" message
• _format_limit() displays period suffix (e.g., tph: 100,000/hour) instead of hardcoded /min
• _format_limit() appends (burst: N) when capacity != refill_amount
• -l help text on all three commands reads 'name:rate[/period][:burst]' with period options listed
• CLI examples updated to demonstrate period syntax in resource set-defaults, system set-defaults, and entity set-limits
• Unit tests cover all period units (/sec, /min, /hour, /day), multiplied periods (/5min), burst with period, and invalid periods

Alternatives Considered

Separate --period flag: Rejected because it couples awkwardly with multiple -l flags (which limit gets which period?). Inline syntax keeps rate and period together.

Use ISO 8601 duration (PT1H): Overly verbose for CLI usage. /hour is more intuitive for the target audience (ops/platform engineers).