feat: surface Gemara bundle metadata via CLI for informed configuration

[sonupreetam]

Problem

After complyctl get pulls a Gemara bundle from an OCI registry, the CLI discards everything it learned about the bundle content. The user has no way to discover:

• What policy is inside the bundle (its canonical name, title, description)
• What evaluator it requires (openscap, ampel, opa)
• What target variables that evaluator needs
• Whether their chosen id in complytime.yaml has any relationship to the actual policy

The policies[].id field in complytime.yaml is a purely local alias — it is never validated against or suggested from the bundle's internal metadata. A user writing id: banana would work identically to id: cis-fedora-l1-workstation-policy. The config has zero awareness of what's inside the bundle.

What the bundle already contains

The OCI config blob (fetched during get) has structured metadata:

{
  "bundle-version": "1",
  "artifacts": [
    {
      "id": "cis-fedora-l1-workstation-policy",
      "type": "Policy",
      "role": "artifact",
      "dependencies": ["cis-fedora-l1-workstation-catalog.yaml", "cis-fedora-l1-guidance.yaml"]
    }
  ]
}

The policy YAML layer adds: title, metadata.id, adherence.evaluation-methods[].executor.id, and the full assessment plan structure.

All of this is available after a minimal fetch (manifest + config blob = 2 HTTP requests) — the full layers don't even need to be pulled for basic discovery.

Proposed approach

Introduce a way for users to discover bundle metadata before or after pulling. Options (not mutually exclusive):

Option A: complyctl inspect <url>

Lightweight pre-pull discovery. Fetches only the manifest + config blob from the registry (no full pull). Prints:

$ complyctl inspect quay.io/test_complytime/complytime-policies@v0.3.0-rc1-grc

Policy:    cis-fedora-l1-workstation-policy
Title:     CIS Fedora Linux - Level 1 Workstation Policy
Evaluator: openscap
Requires:  profile, datastream
Artifacts: 3 (1 policy, 1 catalog, 1 guidance)

Option B: Enrich complyctl list output

After get, show bundle-internal metadata alongside the user-chosen ID:

POLICY ID   VERSION         BUNDLE POLICY                        EVALUATOR
cis-fedora  v0.3.0-rc1-grc  cis-fedora-l1-workstation-policy    openscap

Option C: complyctl get prints a summary

After successful sync, report what was pulled:

Syncing policy 1/1: cis-fedora... done
  → Policy: cis-fedora-l1-workstation-policy (openscap)
  → Required variables: profile
  → Artifacts: 3 layers (72K policy, 89K catalog, 12K guidance)

Why this matters

• Users currently have to oras blob fetch and manually inspect JSON to understand what they pulled
• The id in complytime.yaml is disconnected from bundle identity — a config can look correct but reference the wrong policy version/content without any warning
• With multiple policies from the same repository (different tags), the derived ID would always be the same (complytime-policies), giving no hint about what's actually inside
• New providers (OPA, future evaluators) will make this worse — users need to know which evaluator a policy uses to know what variables to configure

References

• internal/policy/loader.go — isBundleManifest(), LoadBundleFiles(), DetectManifestShape()
• internal/cache/ — NewSync(), OCI layout access
• internal/registry/client.go — NewRemoteRepository(), manifest fetch
• Bundle manifest type: bundle.MediaTypeManifest (application/vnd.gemara.manifest.v1+json)

Related

• feat: doctor should validate target variables against provider RequiredTargetVariables #505 — doctor should validate target variables against provider requirements (complementary: that issue catches missing variables; this issue helps users know what variables to provide in the first place)