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

<!-- 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/artifactset_test.go

@@ -81,10 +81,26 @@ var _ = Describe("artifact management", func() {
 		for _, fi := range infos {
 			blobs = append(blobs, fi.Name())
 		}
-		Expect(blobs).To(ContainElements(
-			"sha256.3d05e105e350edf5be64fe356f4906dd3f9bf442a279e4142db9879bba8e677a",
-			"sha256.44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a",
-			"sha256.810ff2fb242a5dee4220f2cb0e6a519891fb67f2f828a6cab4ef8894633b1f50"))
+		if format == artifactset.FORMAT_OCI {
+			// OCI format uses nested directory structure: blobs/sha256/DIGEST
+			Expect(blobs).To(ContainElement("sha256"))
+			subInfos, err := vfs.ReadDir(tempfs, "test/"+artifactset.BlobsDirectoryName+"/sha256")
+			Expect(err).To(Succeed())
+			subBlobs := []string{}
+			for _, fi := range subInfos {
+				subBlobs = append(subBlobs, fi.Name())
+			}
+			Expect(subBlobs).To(ContainElements(
+				"3d05e105e350edf5be64fe356f4906dd3f9bf442a279e4142db9879bba8e677a",
+				"44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a",
+				"810ff2fb242a5dee4220f2cb0e6a519891fb67f2f828a6cab4ef8894633b1f50"))
+		} else {
+			// OCM format uses flat structure: blobs/sha256.DIGEST
+			Expect(blobs).To(ContainElements(
+				"sha256.3d05e105e350edf5be64fe356f4906dd3f9bf442a279e4142db9879bba8e677a",
+				"sha256.44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a",
+				"sha256.810ff2fb242a5dee4220f2cb0e6a519891fb67f2f828a6cab4ef8894633b1f50"))
+		}
 	})
 
 	TestForAllFormats("instantiate tgz artifact", func(format string) {
@@ -108,6 +124,7 @@ var _ = Describe("artifact management", func() {
 		tr := tar.NewReader(zip)
 
 		files := []string{}
+		dirs := []string{}
 		for {
 			header, err := tr.Next()
 			if err != nil {
@@ -119,19 +136,33 @@ var _ = Describe("artifact management", func() {
 
 			switch header.Typeflag {
 			case tar.TypeDir:
-				Expect(header.Name).To(Equal(artifactset.BlobsDirectoryName))
+				dirs = append(dirs, header.Name)
 			case tar.TypeReg:
 				files = append(files, header.Name)
 			}
 		}
+
+		// Check directories
+		Expect(dirs).To(ContainElement(artifactset.BlobsDirectoryName))
+		if format == artifactset.FORMAT_OCI {
+			Expect(dirs).To(ContainElement("blobs/sha256"))
+		}
+
+		// Check files based on format
 		elems := []interface{}{
 			artifactset.DescriptorFileName(format),
-			"blobs/sha256.3d05e105e350edf5be64fe356f4906dd3f9bf442a279e4142db9879bba8e677a",
-			"blobs/sha256.44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a",
-			"blobs/sha256.810ff2fb242a5dee4220f2cb0e6a519891fb67f2f828a6cab4ef8894633b1f50",
 		}
 		if format == artifactset.FORMAT_OCI {
 			elems = append(elems, artifactset.OCILayouFileName)
+			elems = append(elems,
+				"blobs/sha256/3d05e105e350edf5be64fe356f4906dd3f9bf442a279e4142db9879bba8e677a",
+				"blobs/sha256/44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a",
+				"blobs/sha256/810ff2fb242a5dee4220f2cb0e6a519891fb67f2f828a6cab4ef8894633b1f50")
+		} else {
+			elems = append(elems,
+				"blobs/sha256.3d05e105e350edf5be64fe356f4906dd3f9bf442a279e4142db9879bba8e677a",
+				"blobs/sha256.44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a",
+				"blobs/sha256.810ff2fb242a5dee4220f2cb0e6a519891fb67f2f828a6cab4ef8894633b1f50")
 		}
 		Expect(files).To(ContainElements(elems))
 	})
@@ -160,6 +191,7 @@ var _ = Describe("artifact management", func() {
 		tr := tar.NewReader(zip)
 
 		files := []string{}
+		dirs := []string{}
 		for {
 			header, err := tr.Next()
 			if err != nil {
@@ -171,19 +203,33 @@ var _ = Describe("artifact management", func() {
 
 			switch header.Typeflag {
 			case tar.TypeDir:
-				Expect(header.Name).To(Equal(artifactset.BlobsDirectoryName))
+				dirs = append(dirs, header.Name)
 			case tar.TypeReg:
 				files = append(files, header.Name)
 			}
 		}
+
+		// Check directories
+		Expect(dirs).To(ContainElement(artifactset.BlobsDirectoryName))
+		if format == artifactset.FORMAT_OCI {
+			Expect(dirs).To(ContainElement("blobs/sha256"))
+		}
+
+		// Check files based on format
 		elems := []interface{}{
 			artifactset.DescriptorFileName(format),
-			"blobs/sha256.3d05e105e350edf5be64fe356f4906dd3f9bf442a279e4142db9879bba8e677a",
-			"blobs/sha256.44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a",
-			"blobs/sha256.810ff2fb242a5dee4220f2cb0e6a519891fb67f2f828a6cab4ef8894633b1f50",
 		}
 		if format == artifactset.FORMAT_OCI {
 			elems = append(elems, artifactset.OCILayouFileName)
+			elems = append(elems,
+				"blobs/sha256/3d05e105e350edf5be64fe356f4906dd3f9bf442a279e4142db9879bba8e677a",
+				"blobs/sha256/44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a",
+				"blobs/sha256/810ff2fb242a5dee4220f2cb0e6a519891fb67f2f828a6cab4ef8894633b1f50")
+		} else {
+			elems = append(elems,
+				"blobs/sha256.3d05e105e350edf5be64fe356f4906dd3f9bf442a279e4142db9879bba8e677a",
+				"blobs/sha256.44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a",
+				"blobs/sha256.810ff2fb242a5dee4220f2cb0e6a519891fb67f2f828a6cab4ef8894633b1f50")
 		}
 		Expect(files).To(ContainElements(elems))
 	})

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

@@ -138,6 +138,7 @@ var _ = Describe("CTF to CTF-with-resource to OCI roundtrip", Ordered, func() {
 			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)
 

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

@@ -1,6 +1,8 @@
 package artifactset
 
 import (
+	"path/filepath"
+	"strings"
 	"sync"
 
 	"github.com/mandelsoft/goutils/errors"
@@ -42,6 +44,7 @@ func DescriptorFileName(format string) string {
 
 type accessObjectInfo struct {
 	accessobj.DefaultAccessObjectInfo
+	ociFormat bool
 }
 
 var _ accessobj.AccessObjectInfo = (*accessObjectInfo)(nil)
@@ -61,7 +64,7 @@ func validateDescriptor(data []byte) error {
 
 func NewAccessObjectInfo(fmts ...string) accessobj.AccessObjectInfo {
 	a := &accessObjectInfo{
-		baseInfo,
+		DefaultAccessObjectInfo: baseInfo,
 	}
 	oci := IsOCIDefaultFormat()
 	if len(fmts) > 0 {
@@ -84,6 +87,19 @@ func NewAccessObjectInfo(fmts ...string) accessobj.AccessObjectInfo {
 func (a *accessObjectInfo) setOCI() {
 	a.DescriptorFileName = OCIArtifactSetDescriptorFileName
 	a.AdditionalFiles = []string{OCILayouFileName}
+	a.ociFormat = true
+}
+
+// SubPath returns the path for a blob. For OCI format, converts "sha256.DIGEST"
+// to "blobs/sha256/DIGEST" per OCI Image Layout Specification.
+func (a *accessObjectInfo) SubPath(name string) string {
+	if a.ociFormat {
+		// Convert sha256.DIGEST to sha256/DIGEST for OCI compliance
+		if algo, dig, ok := strings.Cut(name, "."); ok {
+			return filepath.Join(a.ElementDirectoryName, algo, dig)
+		}
+	}
+	return filepath.Join(a.ElementDirectoryName, name)
 }
 
 func (a *accessObjectInfo) setOCM() {

api/ocm/extensions/download/handlers/ocilayout/handler.go

@@ -1,7 +1,6 @@
 package ocilayout
 
 import (
-	"path/filepath"
 	"strings"
 
 	"github.com/mandelsoft/goutils/errors"
@@ -71,22 +70,19 @@ func (h *Handler) Download(p common.Printer, racc cpi.ResourceAccess, path strin
 		return true, "", errors.Wrapf(err, "create OCI layout")
 	}
 
-	// Step 6: Transfer all manifests and blobs to target with resource version as tag
-	version := racc.Meta().GetVersion()
-	if err := artifactset.TransferArtifact(art, target, version); err != nil {
-		target.Close()
+	// Step 6: Transfer all manifests and blobs to target with hybrid tagging:
+	// - Original tags from source (e.g., "latest", "linux")
+	// - Resource version (e.g., "1.0.0")
+	tags := collectTags(src, racc.Meta().GetVersion())
+	if err := artifactset.TransferArtifact(art, target, tags...); err != nil {
+		err = errors.Join(err, target.Close())
 		return true, "", errors.Wrapf(err, "transfer artifact")
 	}
 
 	if err := target.Close(); err != nil {
 		return true, "", errors.Wrapf(err, "close target")
 	}
 
-	// Step 7: Convert blob paths from sha256.DIGEST to sha256/DIGEST
-	if err := convertBlobPaths(fs, path); err != nil {
-		return true, "", err
-	}
-
 	p.Printf("%s: downloaded to OCI layout\n", path)
 	return true, path, nil
 }
@@ -96,36 +92,34 @@ func isOCIArtifact(mime string) bool {
 		(strings.HasSuffix(mime, "+tar") || strings.HasSuffix(mime, "+tar+gzip"))
 }
 
-// convertBlobPaths converts blob paths from artifactset format (sha256.DIGEST)
-// to OCI Image Layout format (sha256/DIGEST).
-//
-// This is needed because artifactset uses DigestToFileName which always produces
-// "sha256.DIGEST" format. The FORMAT_OCI option only controls the descriptor file
-// (index.json) and oci-layout file creation, not the blob path structure.
-//
-// Call trace where DigestToFileName is invoked:
-//
-//	TransferArtifact() -> TransferManifest() -> set.AddBlob()
-//	  -> accessobj.FileSystemBlobAccess.AddBlob()
-//	    -> path := a.DigestPath(blob.Digest())
-//	      -> common.DigestToFileName(digest)  // returns "sha256.DIGEST"
-func convertBlobPaths(fs vfs.FileSystem, dir string) error {
-	blobsDir := filepath.Join(dir, "blobs")
-	entries, err := vfs.ReadDir(fs, blobsDir)
-	if err != nil {
-		return err
+// collectTags returns a deduplicated list of tags combining:
+// - Resource version FIRST (becomes org.opencontainers.image.ref.name for ORAS resolution)
+// - Original tags from the source artifact set (preserves mutable refs like "latest")
+func collectTags(src *artifactset.ArtifactSet, version string) []string {
+	seen := make(map[string]struct{})
+	var tags []string
+
+	// Add resource version first - it becomes the primary tag (org.opencontainers.image.ref.name)
+	if version != "" {
+		seen[version] = struct{}{}
+		tags = append(tags, version)
 	}
 
-	for _, e := range entries {
-		if e.IsDir() {
-			continue
-		}
-		name := e.Name()
-		if algo, dig, ok := strings.Cut(name, "."); ok {
-			algoDir := filepath.Join(blobsDir, algo)
-			fs.MkdirAll(algoDir, 0o755)
-			fs.Rename(filepath.Join(blobsDir, name), filepath.Join(algoDir, dig))
+	// Add original tags from source index annotations
+	mainDigest := src.GetMain()
+	for _, m := range src.GetIndex().Manifests {
+		if m.Digest == mainDigest && m.Annotations != nil {
+			if tagStr := artifactset.RetrieveTags(m.Annotations); tagStr != "" {
+				for _, t := range strings.Split(tagStr, ",") {
+					t = strings.TrimSpace(t)
+					if _, ok := seen[t]; !ok && t != "" {
+						seen[t] = struct{}{}
+						tags = append(tags, t)
+					}
+				}
+			}
 		}
 	}
-	return nil
+
+	return tags
 }

api/utils/accessobj/filesystemaccess.go

@@ -4,6 +4,7 @@ import (
 	"fmt"
 	"io"
 	"os"
+	"path/filepath"
 	"sync"
 
 	"github.com/mandelsoft/vfs/pkg/vfs"
@@ -140,6 +141,14 @@ func (a *FileSystemBlobAccess) AddBlob(blob blobaccess.BlobAccess) error {
 	}
 
 	defer r.Close()
+
+	// Create parent directory if path uses nested structure (e.g., blobs/sha256/DIGEST vs blobs/sha256.DIGEST)
+	if dir := filepath.Dir(path); dir != a.base.GetInfo().GetElementDirectoryName() {
+		if err := a.base.GetFileSystem().MkdirAll(dir, a.base.GetMode()|0o111); err != nil {
+			return fmt.Errorf("unable to create directory for '%s': %w", path, err)
+		}
+	}
+
 	w, err := a.base.GetFileSystem().OpenFile(path, os.O_WRONLY|os.O_CREATE|os.O_TRUNC, a.base.GetMode()&0o666)
 	if err != nil {
 		return fmt.Errorf("unable to open file '%s': %w", path, err)