-spec export_directory(ocibuild:image(), file:filename()) -> ok | {error, term()}.

Export image as an OCI layout directory.

Creates the standard OCI directory structure at the given path.

ok = ocibuild_layout:export_directory(Image, "./myimage").

-spec load_tarball_for_push(file:filename()) ->
                               {ok,
                                #{images := [loaded_image()],
                                  tag := binary() | undefined,
                                  is_multi_platform := boolean(),
                                  cleanup := fun(() -> ok)}} |
                               {error, term()}.

Load an OCI image tarball for pushing to a registry.

Parses the OCI Image Layout tarball and extracts all necessary data for pushing: manifests, configs, and layer blobs.

Supports both single-image and multi-platform tarballs. The tag is extracted from index.json annotations if present.

Uses hybrid memory/disk loading: small images (<100MB) are loaded into memory, larger images are extracted to a temp directory.

{ok, Result} = ocibuild_layout:load_tarball_for_push("myimage.tar.gz"),
%% Result = #{
%%     images := [loaded_image()],
%%     tag := binary() | undefined,
%%     is_multi_platform := boolean(),
%%     cleanup := fun(() -> ok)
%% }

-spec load_tarball_for_push(file:filename(), #{memory_threshold => pos_integer()}) ->
                               {ok,
                                #{images := [loaded_image()],
                                  tag := binary() | undefined,
                                  is_multi_platform := boolean(),
                                  cleanup := fun(() -> ok)}} |
                               {error, term()}.

Load an OCI image tarball with options.

Options:

• memory_threshold: File size threshold for in-memory loading (default: 100MB). Files smaller than this are loaded entirely into memory for speed. Larger files are extracted to a temp directory for memory efficiency.

-spec pmap_bounded(fun((A) -> B), [A], pos_integer()) -> [B] when A :: term(), B :: term().

Parallel map with bounded concurrency.

Executes Fun on each element of List in parallel, with at most MaxWorkers concurrent executions. Results are returned in the same order as the input list.

Example:

Results = pmap_bounded(fun(X) -> X * 2 end, [1, 2, 3, 4, 5], 2).
%% Returns [2, 4, 6, 8, 10] with max 2 concurrent workers

Throws if any worker fails with the original error.

-spec save_tarball(ocibuild:image(), file:filename()) -> ok | {error, term()}.

Save image as an OCI layout tarball.

Creates a tar.gz file that can be loaded with podman load or other OCI-compliant tools.

ok = ocibuild_layout:save_tarball(Image, "./myimage.tar.gz").
ok = ocibuild_layout:save_tarball(Image, "./myimage.tar.gz", #{tag => ~"myapp:1.0"}).

Options:

• tag: Image tag annotation (e.g., ~"myapp:1.0")

Note: OCI layout works with podman, skopeo, crane, buildah, and other OCI tools.