Skip to content

bundle.fetch(): record the catalogue format in snapshots #23

Open

Description

@manykarim

Summary

Record the catalogue format, and the package version that built it, in a fetched snapshot, and expose the format on Snapshot:

// <cache>/<sha>/snapshot.json
{
  "repository": "MarketSquare/robotframework-plugins",
  "ref": "latest",
  "commit": "56547f0e579985096a82ce512902c5b4a04269ad",
  "fetched_at": "2026-11-16T12:00:00+00:00",
  "catalog_format": 1,
  "built_by": "robotframework-plugins 2026.11.0.dev1"
}
snap = bundle.fetch("latest")
snap.catalog_format      # 1

Purpose

bundle.CATALOG_FORMAT tells a caller whether it understands bundle.catalog(). A snapshot has no equivalent. Its catalog.json is built with the installed wheel's _catalog rules, so today the format is implied by the wheel that fetched it. But the snapshot stays in the shared cache (%LOCALAPPDATA%/robotframework-plugins/snapshots/<sha> or ~/.cache/...), and fetch() returns a cached snapshot without rebuilding it. When a later wheel changes the catalogue format, it gets an old snapshot built with the old rules, and nothing in the snapshot says so.

rf-mcp checks CATALOG_FORMAT before it serves the bundled skills, and skips them with a warning if it doesn't support the format. It is going to serve snapshots too, for users who opt in to a ref (RF_MCP_OFFICIAL_SKILLS=stable | latest | <tag> | <sha>), and it needs the same check there: serve a cached snapshot only if its format is supported, otherwise fetch again or fall back to the wheel.

Proposed change

  1. Write catalog_format (the CATALOG_FORMAT of the building wheel) and built_by into snapshot.json.
  2. Add Snapshot.catalog_format, read from snapshot.json, and None for snapshots written before this change.
  3. In fetch(), treat a cached snapshot whose catalog_format differs from the running wheel's CATALOG_FORMAT (or is missing) as a cache miss and build it again. Callers then never get a snapshot in a format the running wheel doesn't produce.

Acceptance

  • snapshot.json contains catalog_format and built_by.
  • Snapshot.catalog_format exists and is documented in the README's Python API section.
  • A cached snapshot with another or no format is rebuilt by fetch().

Related: #5 (public bundle API, which added fetch()).

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions