Add online detection CLI command with configurable caching

[Copilot]

Overview

Adds a new aignostics system online CLI command to check network connectivity with intelligent caching to minimize unnecessary network requests.

Changes

CLI Command

Added aignostics system online command that:

• Returns exit code 0 when online (success)
• Returns exit code 1 when offline (failure)
• Displays green message "System is online" when connected
• Displays red message "System is not online" when disconnected

Service Method

Implemented is_online() method in the system service that:

• Leverages existing _determine_network_health() infrastructure
• Checks connectivity to https://api.ipify.org (reliable, well-known endpoint)
• Returns boolean indicating online status

Smart Caching

Implemented efficient caching mechanism to avoid excessive network checks:

• Default TTL: 60 seconds
• Configurable via AIGNOSTICS_SYSTEM_ONLINE_CACHE_TTL_SECONDS environment variable
• Minimum value: 0 (disables caching for always-fresh checks)
• Cache stores result and timestamp as tuple for minimal memory footprint

Tests

Added comprehensive test coverage:

• 6 service tests covering cache behavior, TTL expiration, and configuration
• 2 CLI tests validating exit codes and output for both online and offline scenarios

Usage

Basic check

aignostics system online
# Output: System is online (in green)
# Exit code: 0

Custom cache TTL

export AIGNOSTICS_SYSTEM_ONLINE_CACHE_TTL_SECONDS=30
aignostics system online

Disable caching

export AIGNOSTICS_SYSTEM_ONLINE_CACHE_TTL_SECONDS=0
aignostics system online  # Always checks network

In shell scripts

#!/bin/bash
if aignostics system online; then
    echo "Connected! Proceeding with online operations..."
    # Perform online operations
else
    echo "Offline. Cannot proceed."
    exit 1
fi

Technical Details

• Cache implementation: Simple tuple (is_online, timestamp) stored at class level
• Network check: Uses existing _determine_network_health() method with 5-second timeout
• Thread-safety: Not required (CLI operations are single-threaded per invocation)
• Logging: Debug-level logs for cache hits/misses to aid troubleshooting

Design Decisions

1. Reused existing infrastructure: Leverages _determine_network_health() which already checks api.ipify.org
2. Minimal changes: Only 178 lines added across 5 files
3. Unix conventions: Exit codes follow standard conventions (0=success, non-zero=failure)
4. Color-coded output: Uses existing console styles for consistency
5. Configurable defaults: 60-second cache balances freshness with efficiency

Files Modified

• src/aignostics/system/_settings.py (+9 lines) - Added online_cache_ttl_seconds setting
• src/aignostics/system/_service.py (+31 lines) - Implemented is_online() with caching
• src/aignostics/system/_cli.py (+16 lines) - Added online CLI command
• tests/aignostics/system/service_test.py (+106 lines) - Service tests
• tests/aignostics/system/cli_test.py (+16 lines) - CLI tests

Closes #[issue-number]

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• astral.sh
  • Triggering command: curl -LsSf REDACTED (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>PR with online detection</issue_title>
<issue_description>Add CLI command "aignostics system online" which exits with 1 if not online, 0 otherwise, and prints info if online (green) or not (red).

For that provide is_online() in system service, drawing from system info, as in using well known and reliable source to check connectivity.

Cache online information for 60 seconds (default), with that number configurable in settings of system module.

Provide tests for the above in tests directory of system module.</issue_description>

Comments on the Issue (you are @copilot in this section)

Fixes #151

---

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.

[Copilot]

Copilot wasn't able to review any files in this pull request.