fix: add --oci-layout flag for ocm download resource

<!-- markdownlint-disable MD041 -->
This change adds an optional --oci-layout flag to the
`ocm download artifacts` command to store blobs at
blobs/<algorithm>/<encoded> per OCI Image Layout Specification
instead of the default blobs/<algorithm>.<encoded> format.

This enables compatibility with tools that expect OCI-compliant
blob paths.

<!--
Usage: `Fixes #<issue number>`, or `Fixes (paste link of issue)`.
-->
Fixes #1668

Signed-off-by: Piotr Janik <piotr.janik@sap.com>

Author: piotrjanik

api/oci/extensions/repositories/artifactset/ctf_roundtrip_test.go

@@ -0,0 +1,227 @@
+//go:build integration
+
+package artifactset_test
+
+import (
+	"bytes"
+	"context"
+	"fmt"
+	"os"
+	"path/filepath"
+
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+
+	"github.com/mandelsoft/vfs/pkg/osfs"
+	ocispec "github.com/opencontainers/image-spec/specs-go/v1"
+	"oras.land/oras-go/v2/content"
+	"oras.land/oras-go/v2/content/oci"
+
+	envhelper "ocm.software/ocm/api/helper/env"
+	. "ocm.software/ocm/cmds/ocm/testhelper"
+)
+
+const (
+	componentName    = "example.com/hello"
+	componentVersion = "1.0.0"
+	resourceName     = "hello-image"
+	resourceVersion  = "1.0.0"
+	imageName        = "hello-world"
+	imageTag         = "linux"
+
+	// Use the latest stable OCM release image
+	ocmImage = "ghcr.io/open-component-model/ocm/ocm.software/ocmcli/ocmcli-image:0.34.2"
+)
+
+// verifyOCILayoutWithORAS opens an OCI layout and resolves a tag using ORAS.
+// Returns the descriptor if successful.
+func verifyOCILayoutWithORAS(ctx context.Context, ociDir, tag string) (ocispec.Descriptor, error) {
+	store, err := oci.New(ociDir)
+	if err != nil {
+		return ocispec.Descriptor{}, fmt.Errorf("ORAS failed to open OCI layout: %w", err)
+	}
+
+	srcDesc, err := store.Resolve(ctx, tag)
+	if err != nil {
+		// Try resource version as fallback
+		srcDesc, err = store.Resolve(ctx, resourceVersion)
+		if err != nil {
+			indexData, readErr := os.ReadFile(filepath.Join(ociDir, "index.json"))
+			if readErr == nil {
+				GinkgoWriter.Printf("index.json content: %s\n", string(indexData))
+			}
+			return ocispec.Descriptor{}, fmt.Errorf("ORAS could not resolve tag %q: %w", tag, err)
+		}
+	}
+
+	successors, err := content.Successors(ctx, store, srcDesc)
+	if err != nil {
+		return ocispec.Descriptor{}, fmt.Errorf("ORAS failed to get successors: %w", err)
+	}
+	if len(successors) == 0 {
+		return ocispec.Descriptor{}, fmt.Errorf("ORAS found no successors")
+	}
+	GinkgoWriter.Printf("Found %d successors for tag %q\n", len(successors), tag)
+
+	return srcDesc, nil
+}
+
+// This test verifies the CTF-based workflow with --oci-layout flag:
+//  1. Create a CTF archive using current OCM version
+//  2. Transfer CTF to new CTF with --copy-resources
+//  3. Download resource from new CTF with --oci-layout (creates OCI Image Layout)
+//  4. Verify downloaded OCI layout is compliant with ORAS store.Resolve()
+//  5. Download resource without --oci-layout (creates single file blob)
+//  6. Verify the difference between OCI layout and raw blob download
+var _ = Describe("CTF to CTF-with-resource to OCI roundtrip", Ordered, func() {
+	var (
+		tempDir         string
+		sourceCTF       string
+		targetCTF       string
+		resourcesOciDir string
+		resourcesOcmDir string
+		env             *TestEnv
+	)
+
+	BeforeAll(func() {
+
+		var err error
+		tempDir, err = os.MkdirTemp("", "ocm-ctf-oci-layout-*")
+		Expect(err).To(Succeed())
+
+		env = NewTestEnv(envhelper.FileSystem(osfs.New()))
+	})
+
+	AfterAll(func() {
+		if env != nil {
+			env.Cleanup()
+		}
+	})
+
+	It("creates CTF using stable OCM release", func() {
+		sourceCTF = filepath.Join(tempDir, "ctf-source")
+		constructorFile := filepath.Join(tempDir, "component-constructor.yaml")
+		constructorContent := `components:
+  - name: ` + componentName + `
+    version: ` + componentVersion + `
+    provider:
+      name: example.com
+    resources:
+      - name: ` + resourceName + `
+        type: ociImage
+        version: ` + resourceVersion + `
+        relation: external
+        access:
+          type: ociArtifact
+          imageReference: ` + imageName + `:` + imageTag + `
+`
+		err := os.WriteFile(constructorFile, []byte(constructorContent), 0644)
+		Expect(err).To(Succeed(), "MUST create constructor file")
+
+		// Create CTF directory
+		err = os.MkdirAll(sourceCTF, 0755)
+		Expect(err).To(Succeed(), "MUST create CTF directory")
+
+		// Use the current OCM version to create the CTF
+		GinkgoWriter.Printf("Creating CTF using current OCM version\n")
+
+		buf := bytes.NewBuffer(nil)
+		err = env.CatchOutput(buf).Execute(
+			"add", "componentversions",
+			"--create",
+			"--file", sourceCTF,
+			constructorFile,
+		)
+		GinkgoWriter.Printf("OCM output: %s\n", buf.String())
+		Expect(err).To(Succeed(), "OCM MUST create CTF: %s", buf.String())
+	})
+
+	It("transfers CTF to new CTF with --copy-resources", func() {
+		targetCTF = filepath.Join(tempDir, "ctf-target")
+		buf := bytes.NewBuffer(nil)
+		GinkgoWriter.Printf(" #### transfer componentversions " + sourceCTF + " " + targetCTF + "--copy-resources")
+		Expect(env.CatchOutput(buf).Execute(
+			"transfer", "componentversions", sourceCTF, targetCTF, "--copy-resources")).To(Succeed())
+		GinkgoWriter.Printf("Transfer output: %s\n", buf.String())
+	})
+
+	It("verifies components and resources in target CTF", func() {
+		buf := bytes.NewBuffer(nil)
+		Expect(env.CatchOutput(buf).Execute("get", "componentversions", targetCTF)).To(Succeed())
+		GinkgoWriter.Printf("Components: %s\n", buf.String())
+		Expect(buf.String()).To(ContainSubstring(componentName))
+
+		// List resources
+		buf.Reset()
+		Expect(env.CatchOutput(buf).Execute(
+			"get", "resources",
+			targetCTF+"//"+componentName+":"+componentVersion,
+		)).To(Succeed())
+		GinkgoWriter.Printf("Resources: %s\n", buf.String())
+		Expect(buf.String()).To(ContainSubstring(resourceName))
+	})
+
+	It("downloads resource from target CTF with --oci-layout", func() {
+		resourcesOciDir = filepath.Join(tempDir, "resource-oci-layout")
+
+		buf := bytes.NewBuffer(nil)
+		Expect(env.CatchOutput(buf).Execute(
+			"download", "resources",
+			"--oci-layout",
+			"-O", resourcesOciDir,
+			targetCTF+"//"+componentName+":"+componentVersion,
+			resourceName,
+		)).To(Succeed())
+		Expect(verifyOCILayoutStructure(resourcesOciDir)).To(Succeed())
+		store, err := oci.New(resourcesOciDir)
+		Expect(err).To(Succeed(), "ORAS failed to open OCI layout: %w", err)
+
+		srcDesc, err := store.Resolve(context.Background(), resourceVersion)
+		Expect(err).To(Succeed(), "resource MUST be OCI compliant")
+		GinkgoWriter.Printf("Successfully verified OCI layout with ORAS: digest=%s\n", srcDesc.Digest)
+
+	})
+
+	It("downloads resource from target CTF without --oci-layout", func() {
+		resourcesOcmDir = filepath.Join(tempDir, "resource-ocm-layout")
+
+		buf := bytes.NewBuffer(nil)
+		Expect(env.CatchOutput(buf).Execute(
+			"download", "resources",
+			"-O", resourcesOcmDir,
+			targetCTF+"//"+componentName+":"+componentVersion,
+			resourceName,
+		)).To(Succeed())
+		Expect(verifyOCILayoutStructure(resourcesOcmDir)).ToNot(Succeed())
+		GinkgoWriter.Printf("Resource download output: %s\n", buf.String())
+	})
+})
+
+// verifyOCILayoutStructure checks that the OCI layout has the expected structure.
+// Returns an error if any required file or directory is missing.
+func verifyOCILayoutStructure(ociDir string) error {
+	// Check oci-layout file exists
+	ociLayoutPath := filepath.Join(ociDir, "oci-layout")
+	if _, err := os.Stat(ociLayoutPath); err != nil {
+		return fmt.Errorf("oci-layout file MUST exist: %w", err)
+	}
+
+	// Check index.json exists
+	indexPath := filepath.Join(ociDir, "index.json")
+	if _, err := os.Stat(indexPath); err != nil {
+		return fmt.Errorf("index.json MUST exist: %w", err)
+	}
+
+	// Check blobs directory exists
+	blobsDir := filepath.Join(ociDir, "blobs")
+	info, err := os.Stat(blobsDir)
+	if err != nil {
+		return fmt.Errorf("blobs directory MUST exist: %w", err)
+	}
+	if !info.IsDir() {
+		return fmt.Errorf("blobs MUST be a directory, got file")
+	}
+
+	GinkgoWriter.Printf("OCI layout structure verified: oci-layout, index.json, blobs/\n")
+	return nil
+}