Add Registry Ping Command

[toddysm]

Summary

Implements regshape ping --registry <host> command that checks OCI registry connectivity by issuing GET /v2/ per the OCI Distribution Spec. Closes #32.

Changes

Library Layer (src/regshape/libs/ping/)

• operations.py: ping(client) -> PingResult function that:
  • Issues GET /v2/ via RegistryClient and measures round-trip latency
  • Returns PingResult dataclass with reachable, status_code, api_version (from Docker-Distribution-API-Version header), and latency_ms
  • Raises PingError on connection, DNS, or timeout failures
  • Raises AuthError on HTTP 401 responses
• __init__.py: Re-exports ping and PingResult

CLI Layer (src/regshape/cli/ping.py)

• Top-level ping command registered directly on the regshape group
• Options: --registry/-r (required), --json (flag)
• Auth errors (401/403 token negotiation) are treated as reachable, since the registry responded with a challenge proving connectivity. Output includes a hint to run regshape auth login.
• Exit code 0 on reachable (including auth-required), exit code 1 on unreachable

Other Changes

• PingError added to src/regshape/libs/errors.py
• ping command registered in src/regshape/cli/main.py
• Design spec at specs/cli/ping.md

Usage

# Basic ping
regshape ping --registry ghcr.io

# JSON output
regshape ping --registry ghcr.io --json

# Insecure (HTTP) registry
regshape --insecure ping --registry localhost:5000

Example Output

Registry ghcr.io is reachable
  Note: Registry requires authentication. Run 'regshape auth login' to configure credentials.

{
  "reachable": true,
  "status_code": 200,
  "api_version": "registry/2.0",
  "latency_ms": 42.3,
  "registry": "ghcr.io"
}

Tests

23 unit tests added:

• test_ping_operations.py (11 tests): PingResult serialization, success with/without API version header, non-200 responses, 401 auth error, connection/timeout/generic errors, latency measurement
• test_ping_cli.py (12 tests): plain text and JSON output, exit codes, auth error handling, insecure flag propagation, required option validation

[Copilot]

Pull request overview

Adds a new top-level regshape ping command to validate OCI registry connectivity via GET /v2/, implemented with a small library operation layer and covered by new unit tests/spec documentation.

Changes:

• Introduces regshape.libs.ping with ping(client) and a PingResult model (latency + API version header support).
• Adds regshape ping --registry ... [--json] CLI command and registers it in the main CLI.
• Adds PingError and new unit tests + a design/spec document for the command.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
src/regshape/libs/ping/operations.py	Implements library-level ping and PingResult serialization.
src/regshape/libs/ping/init.py	Re-exports ping API surface.
src/regshape/libs/errors.py	Adds PingError to shared error types.
src/regshape/cli/ping.py	Implements the Click command, JSON/plain output, and exit codes.
src/regshape/cli/main.py	Registers the new top-level ping command.
src/regshape/tests/test_ping_operations.py	Unit tests for ping operation behavior and serialization.
src/regshape/tests/test_ping_cli.py	CLI tests for output modes, exit codes, and flag propagation.
specs/cli/ping.md	Command design/spec and examples/test plan.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.