Enhancement: Support tag references in referrer list with automatic digest resolution

[toddysm]

Description

regshape referrer list currently requires a digest reference (registry/repo@sha256:...) and rejects tag references with exit code 2. This is because the OCI Referrers API endpoint (GET /v2/<name>/referrers/<digest>) requires a digest.

However, users most commonly work with tags rather than digests. The command should accept tag references and automatically resolve them to a digest via a HEAD request before querying the referrers API.

Proposed Behavior

When --image-ref contains a tag reference (e.g. registry/repo:v1.0), the command should:

1. Issue HEAD /v2/<name>/manifests/<tag> to resolve the tag to a digest (via the Docker-Content-Digest response header)
2. Use the resolved digest to call GET /v2/<name>/referrers/<digest>
3. Proceed as normal with the referrer results

When --image-ref already contains a digest, behavior is unchanged.

Acceptance Criteria

• regshape referrer list -i registry/repo:tag resolves the tag and lists referrers
• regshape referrer list -i registry/repo@sha256:... continues to work as before (no regression)
• Tag resolution failure (e.g. tag not found) produces a clear error with exit code 1
• The --json, --all, --artifact-type, and --output flags work with tag references
• Help text and --image-ref description updated to reflect tag support
• Unit tests cover: tag resolution happy path, tag not found error, digest passthrough unchanged
• CLI spec (specs/cli/referrer.md) updated to document tag support

Files to Create/Modify

CLI layer

• src/regshape/cli/referrer.py — Remove the digest-only guard; add tag-to-digest resolution using head_manifest before calling list_referrers/list_referrers_all

Library layer

No changes needed — libs/referrers/operations.py already accepts a digest string, and libs/manifests/operations.py already provides head_manifest(client, repo, reference, accept) which returns (digest, media_type, size).

Tests

• src/regshape/tests/test_referrer_cli.py — Add tests for tag resolution, update test_tag_reference_rejected_with_exit_code_2 to expect success instead of rejection

Specs

• specs/cli/referrer.md — Update accepted formats table and description

Implementation Notes

The tag-to-digest resolution requires a single additional HEAD request. The head_manifest function from libs/manifests already handles this:

from regshape.libs.manifests import head_manifest
from regshape.libs.models.mediatype import ALL_MANIFEST_MEDIA_TYPES

accept = ",".join(sorted(ALL_MANIFEST_MEDIA_TYPES))
digest, _, _ = head_manifest(client, repo, tag, accept)
# Now use digest for the referrers API call

The guard block that currently rejects tags:

if not reference.startswith("sha256:") and not reference.startswith("sha512:"):
    emit_error(...)

should be replaced with a resolution step that calls head_manifest to obtain the digest.

References

• specs/cli/referrer.md — Current CLI spec
• specs/operations/referrers.md — Referrers operations spec
• OCI Distribution Spec: Referrers API requires a digest in the URL path