copy: add InstancePlatforms field for platform-based filtering

[aguidirh]

Add platform-based filtering for copying specific images

This PR adds the ability to select images by platform name (e.g., linux/amd64) instead of requiring digest hashes, implementing the functionality proposed in containers/image#1938.

Motivation

Relates to #227

When copying specific images from a multi-architecture manifest list, the current CopySpecificImages mode requires users to specify exact digest hashes in the Instances field. This is cumbersome because:

1. Poor User Experience: Users must manually look up digest values for each platform
2. Error-Prone: Easy to copy wrong digest or get confused about which digest corresponds to which platform
3. Not Intuitive: Most users think in terms of "amd64" or "arm64", not "sha256:abc123..."

This PR adds a new InstancePlatforms field that allows users to specify platforms by human-readable OS and Architecture names.

Changes

1. New InstancePlatformFilter type and InstancePlatforms field

• Added InstancePlatformFilter struct with OS and Architecture fields
• Added InstancePlatforms []InstancePlatformFilter field to Options struct
• Allows specifying platforms like {OS: "linux", Architecture: "amd64"}
• Only supports OS and Architecture (not Variant, OSVersion, or OSFeatures)
• Works alongside existing Instances field (both can be used simultaneously)

2. Platform resolution in determineSpecificImages()

• New function that combines digest-based and platform-based selection
• Iterates through all instances and copies ALL instances matching the specified OS/Architecture
• This includes all compression variants (gzip, zstd, etc.) for a given platform
• Returns deduplicated Set of digests from both sources
• Clear error messages when requested platform doesn't exist (format: no instances found for platform OS/Architecture)

3. Efficient Set-based filtering

• Refactored from slices.Contains() to Set-based lookup
• Uses set.NewWithValues() for convenient initialization

4. Comprehensive test coverage

• Added TestDetermineSpecificImages with table-driven tests
• Tests platform-only, digest-only, and combined selection
• Tests multi-compression scenarios (verifies ALL variants are copied)
• Tests multi-variant scenarios (verifies ALL variants are copied)
• Validates error handling for non-existent platforms
• All existing tests continue to pass

User Experience Improvement

Before (digest-based only):

options := &copy.Options{
    ImageListSelection: copy.CopySpecificImages,
    Instances: []digest.Digest{
        "sha256:e692418e4cbaf90ca69d05a66403747baa33ee08806650b51fab815ad7fc331f",  // Which platform?
        "sha256:5b0bcabd1ed22e9fb1310cf6c2dec7cdef19f0ad69efa1f392e94a4333501270",  // Which platform?
    },
}

After (platform-based):

options := &copy.Options{
    ImageListSelection: copy.CopySpecificImages,
    InstancePlatforms: []copy.InstancePlatformFilter{
        {OS: "linux", Architecture: "amd64"},
        {OS: "linux", Architecture: "ppc64le"},
    },
}

Combined (both methods):

options := &copy.Options{
    ImageListSelection: copy.CopySpecificImages,
    Instances:         []digest.Digest{specificDigest},      // When you know the exact digest
    InstancePlatforms: []copy.InstancePlatformFilter{        // When you know the platform
        {OS: "linux", Architecture: "arm64"},
    },
}

Multi-Compression Support

When a platform is specified, ALL instances matching that OS/Architecture are copied, including:

• All compression variants (gzip, zstd, uncompressed, etc.)
• All other variations of the same platform

This ensures that users get complete platform coverage without needing to understand the internal compression details.

API Design

The InstancePlatformFilter type only exposes OS and Architecture fields, making it impossible to set unsupported fields (like Variant) at compile time. This is safer than runtime validation and provides a clearer API.

Testing

All existing tests pass. New tests verify:

• ✅ Platform-only selection
• ✅ Digest-only selection (backward compatibility)
• ✅ Combined platform and digest selection
• ✅ Error handling for non-existent platforms
• ✅ Set deduplication when same instance selected by both methods
• ✅ Multi-compression scenarios (all variants copied)
• ✅ Multi-variant scenarios (all variants copied)

Compatibility

• ✅ Fully backward compatible - new optional field
• ✅ Existing code using Instances field continues to work unchanged
• ✅ No breaking changes to public API

Credits

This implementation is based on the original work by @nalind in containers/image#1938, adapted for the container-libs monorepo structure.

[packit-as-a-service]

Packit jobs failed. @containers/packit-build please check.

[packit-as-a-service]

Packit jobs failed. @containers/packit-build please check.

[mtrmac]

Thanks!

An extremely brief look for now.

[TomSweeneyRedHat]

I've approved this and restarted a couple of failng tests. I'd be interested in seeing your reply to @mtrmac 's comment on the multi-compression images.

Overall, a nice change, thanks!

[TomSweeneyRedHat]

LGTM
and happy green test buttons.

[mtrmac]

#656 (comment) still needs addressing.

[mtrmac]

ACK to the implementation.

Please rebase, I think that should fix the Skopeo test failures.

[mtrmac]

Thanks!

LGTM; please squash to avoid the "address review feedback" commit messages.

[aguidirh]

Thanks!

LGTM; please squash to avoid the "address review feedback" commit messages.

All commits squashed as requested.

Please let me know if there is something pending before merging this PR.