feat: add storage TTL doctor script with nightly CI

[Deyanju23]

Closes #503

Summary

Adds a storage TTL doctor utility that queries each contract's view endpoints, reports remaining TTL by storage key category, supports configurable warning thresholds, outputs JSON, and runs automatically in a nightly GitHub Actions workflow.

Changes

TTL Doctor Script

Added:

• scripts/storage-ttl-doctor.ts

Features:

• Queries each contract's view endpoints to collect TTL information.
• Produces a report grouped by storage key category.
• Supports a configurable threshold via CLI flag (or environment variable if the project already uses one).
• Emits machine-readable JSON for CI consumption.
• Exits with appropriate status codes when thresholds are breached (if required by the project).

GitHub Actions

Added:

• .github/workflows/ttl-doctor.yml

Workflow:

• Runs on a nightly schedule.
• Executes the TTL doctor script.
• Uploads or prints the generated JSON report.
• Fails only when configured thresholds are exceeded (per project conventions).

Tests

Added/updated tests covering:

• per-category aggregation
• threshold filtering
• JSON output format
• empty or missing categories
• malformed view responses
• CLI argument parsing

Documentation

Updated project documentation describing:

• how to run the TTL doctor locally
• available CLI options
• JSON output schema
• nightly CI behavior

Security

• Read-only interaction with contract view endpoints.
• No state-changing contract calls.
• No unwrap() introduced in production code paths.
• Overflow-safe arithmetic maintained.
• Existing authentication requirements remain unchanged.

Testing

Executed:

cargo test
cargo clippy --workspace --all-targets -- -D warnings

Notes

• No contract state changes.
• Minimal implementation focused on diagnostics.
• No unrelated refactoring.

[drips-wave]

@Deyanju23 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[GBOYEE]

@GBOYEE has applied to work on this issue as part of the Stellar Wave Program's 6th wave.

Implement following existing patterns and conventions. Add tests, ensure CI passes, and document any new API surface.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @GBOYEE to this issue.