[FEATURE] - Support optional ref field on marketplace module entries

[dmartinol]

Feature Description

Add an optional ref field to marketplace module entries so Lola can install modules from a specific Git revision instead of always using the repository default branch.

ref should accept any valid Git reference: branch name, tag, or commit SHA (full or short, as supported by the underlying Git client).

Example marketplace entry:

modules:
  - name: partner-network-tools
    description: Network troubleshooting skills for SDN and OVN diagnostics
    version: 1.2.0
    repository: https://github.com/partner-org/network-skills
    ref: a1b2c3d4e5f6789012345678901234567890abcd  # commit SHA
    path: .
    tags: [networking, sdn, troubleshooting]

  - name: stable-tools
    description: Skills pinned to a release tag
    version: 2.0.0
    repository: https://github.com/org/tools
    ref: v2.0.0  # tag
    path: packs/tools
    tags: [tools]

  - name: dev-preview
    description: Skills from a development branch
    version: 0.9.0
    repository: https://github.com/org/tools
    ref: develop  # branch
    path: packs/tools
    tags: [preview]

When ref is present, lola install, lola mod add, and lola mod update should fetch and install from that revision. When omitted, behavior should remain unchanged (default branch).

Problem or Use Case

Marketplace curators need to pin federated or third-party modules to known-good revisions for supply-chain reproducibility and reviewability. Without ref support in Lola:

1. A marketplace may declare a pinned commit in YAML, but Lola silently ignores it and installs whatever is on the default branch today.
2. Users who trust a marketplace catalog get a different module content than the curator validated.
3. Curators must embed the revision in the repository URL (e.g. repo.git@v1.0.0), which is non-standard, harder to validate, and inconsistent with separate path handling for monorepos.

The Red Hat Agentic Collections federation workflow already requires a ref field (commit SHA) on federated module entries, but Lola does not honor it — the field is documented as a project extension that Lola ignores. CI in that repo validates packs at the pinned ref, yet end-user installs via lola install -f <name> do not respect that pin.

Category

Marketplace

Proposed Solution

1. Schema — Document ref as an optional module field in the marketplace YAML format (alongside name, description, version, repository, path, tags).
2. Install path — When resolving a module from a marketplace, if ref is set, clone/fetch at that revision before installing from path.
3. Updates — lola mod update should re-fetch using the marketplace-defined ref (or record the resolved SHA for traceability).
4. Validation — Reject or warn on invalid refs at marketplace parse/cache time where feasible.
5. Backward compatibility — Omitting ref keeps current default-branch behavior.

This aligns with existing Lola support for refs in .lola-req URLs (https://github.com/user/module.git@main), but brings the same capability to marketplace module metadata.

Alternatives Considered

• Embed ref in repository URL (repo.git@<ref>) — works for direct lola mod add but not for marketplace-driven install; duplicates ref when path is also used.
• Rely on version only — semver does not map reliably to a Git revision without tags; insufficient for commit-level pinning.
• Curator-side fork/mirror — heavy operational burden; does not scale for federation.

Complexity Estimate

Medium

Additional Context

• Lola already documents ref support in declarative .lola-req files via URL fragments (@main, @tag).
• Federation marketplaces (e.g. agentic-collections) use ref + path together for external repos; path selects the pack subdirectory and ref should select the Git revision.
• Prefer resolving tags/branches to a concrete commit SHA internally for reproducibility, while accepting branch/tag/SHA as input.