# Specification: Cluster Status Script (`cluster_status_python`)

## Overview
Create a Python-based CLI script to be run on a local system (outside the cluster) to monitor the health and status of the Navidrome LiteFS/Consul cluster. This tool will bridge the gap for local monitoring without needing a local Consul instance.

## Functional Requirements
- **Consul Connectivity:** 
    - Connect to a remote Consul instance.
    - Default to a hardcoded URL with support for overrides via command-line arguments (e.g., `--consul-url`) or environment variables (`CONSUL_HTTP_ADDR`).
    - Assume no Consul authentication token is required.
- **Service Discovery:**
    - Query Consul for the `navidrome` (Primary) and `replica-navidrome` (Replica) services.
    - Verify that services are registered correctly and health checks are passing.
- **Status Reporting:**
    - Display a text-based table summarizing the state of all nodes in the cluster.
    - Color-coded output for quick health assessment.
    - Include a summary section at the top indicating overall cluster health.
- **Node-Level Details:**
    - Role identification (Primary vs. Replica).
    - Uptime of the LiteFS process.
    - Advertise URL for each node.
    - Replication Lag (for Replicas).
    - Write-forwarding proxy target (for Replicas).

## Non-Functional Requirements
- **Language:** Python 3.x.
- **Dependencies:** Use standard libraries or common packages like `requests` for API calls and `tabulate` for table formatting.
- **Portability:** Must run on Linux (user's OS) without requiring local Consul or Nomad binaries.

## Acceptance Criteria
- [ ] Script successfully retrieves service list from remote Consul.
- [ ] Script correctly identifies the current Primary node based on Consul tags/service names.
- [ ] Script queries the LiteFS HTTP API (`:20202/status`) on each node to gather internal metrics.
- [ ] Output is formatted as a clear, readable text table.
- [ ] Overrides for Consul URL are functional.

## Out of Scope
- Direct interaction with Nomad API (Consul is the source of truth for this script).
- Database-level inspection (SQL queries).
- Remote log tailing.