Store typed ReleaseKit manifests

Author: dannote

CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## v0.2.1 - 2026-06-23
+
+### Changed
+
+- Changed ETF manifests to store the typed `%ReleaseKit.Manifest{}` contract directly.
+- Added `ReleaseKit.Manifest.read!/1` and validation for typed manifest consumers.
+
 ## v0.2.0 - 2026-06-23
 
 ### Added

README.md

@@ -164,10 +164,10 @@ MIX_ENV=prod mix release_kit.artifact --out-dir _build/prod/artifacts
 
 ## Manifest shape
 
-The manifest is an ETF-encoded map:
+The manifest is an ETF-encoded `%ReleaseKit.Manifest{}` struct:
 
 ```elixir
-%{
+%ReleaseKit.Manifest{
   tool: "release_kit",
   format: :beam_release_artifact,
   format_version: 2,
@@ -176,7 +176,7 @@ The manifest is an ETF-encoded map:
   version: "20260620-abcdef0",
   mix_env: "prod",
   tarball: "/absolute/path/to/my_app-20260620-abcdef0.tar.gz",
-  artifact: %{
+  artifact: %ReleaseKit.ArtifactInfo{
     path: "/absolute/path/to/my_app-20260620-abcdef0.tar.gz",
     size: 1_234_567,
     compression: :gzip,
@@ -186,16 +186,16 @@ The manifest is an ETF-encoded map:
       sidecar: "/absolute/path/to/my_app-20260620-abcdef0.tar.gz.sha256"
     }
   },
-  target: %{os: "linux", arch: "x86_64", libc: "glibc"},
-  build: %{
+  target: %ReleaseKit.Target{os: "linux", arch: "x86_64", libc: "glibc"},
+  build: %ReleaseKit.BuildInfo{
     release_kit_version: "0.2.0",
     elixir_version: "1.20.0",
     otp_version: "28",
     git_revision: "abcdef0",
     git_dirty?: false
   },
   assets: [
-    %{
+    %ReleaseKit.AssetInfo{
       tool: :volt,
       profile: :my_app_web,
       outdir: "priv/static/assets",

lib/release_kit/manifest.ex

@@ -72,21 +72,6 @@ defmodule ReleaseKit.Manifest do
     }
   end
 
-  @doc """
-  Converts a manifest struct to the stable external map stored in ETF files.
-  """
-  @spec to_external_map(t()) :: map()
-  def to_external_map(%__MODULE__{} = manifest) do
-    manifest
-    |> Map.from_struct()
-    |> Map.update!(:artifact, &external_artifact/1)
-    |> Map.update!(:target, &external_target/1)
-    |> Map.update!(:build, &external_build/1)
-    |> Map.update!(:assets, &external_assets/1)
-    |> Enum.reject(fn {_key, value} -> is_nil(value) or value == [] end)
-    |> Map.new()
-  end
-
   @doc """
   Writes a manifest as ETF.
   """
@@ -96,29 +81,35 @@ defmodule ReleaseKit.Manifest do
     |> Path.dirname()
     |> File.mkdir_p!()
 
-    File.write!(path, :erlang.term_to_binary(to_external_map(manifest)))
+    File.write!(path, :erlang.term_to_binary(manifest))
   end
 
-  defp external_artifact(nil), do: nil
-
-  defp external_artifact(%ReleaseKit.ArtifactInfo{} = artifact),
-    do: ReleaseKit.ArtifactInfo.to_external_map(artifact)
-
-  defp external_target(nil), do: nil
-
-  defp external_target(%ReleaseKit.Target{} = target),
-    do: ReleaseKit.Target.to_external_map(target)
+  @doc """
+  Reads a typed manifest from ETF.
+  """
+  @spec read!(Path.t()) :: t()
+  def read!(path) when is_binary(path) do
+    path
+    |> File.read!()
+    |> :erlang.binary_to_term()
+    |> validate!()
+  end
 
-  defp external_build(nil), do: nil
+  @doc """
+  Validates a typed manifest contract.
+  """
+  @spec validate!(term()) :: t()
+  def validate!(%__MODULE__{format: :beam_release_artifact, format_version: 2} = manifest) do
+    manifest
+  end
 
-  defp external_build(%ReleaseKit.BuildInfo{} = build),
-    do: ReleaseKit.BuildInfo.to_external_map(build)
+  def validate!(%__MODULE__{} = manifest) do
+    raise ArgumentError,
+          "unsupported ReleaseKit manifest #{inspect(manifest.format)} v#{inspect(manifest.format_version)}"
+  end
 
-  defp external_assets(assets) do
-    Enum.map(assets, fn
-      %ReleaseKit.AssetInfo{} = asset -> ReleaseKit.AssetInfo.to_external_map(asset)
-      asset -> asset
-    end)
+  def validate!(other) do
+    raise ArgumentError, "expected %ReleaseKit.Manifest{}, got: #{inspect(other)}"
   end
 
   defp env(opts) do

mix.exs

@@ -4,7 +4,7 @@ defmodule ReleaseKit.MixProject do
   def project do
     [
       app: :release_kit,
-      version: "0.2.0",
+      version: "0.2.1",
       elixir: "~> 1.20",
       start_permanent: Mix.env() == :prod,
       deps: deps(),

test/mix/tasks/release_kit.artifact_test.exs

@@ -41,8 +41,8 @@ defmodule Mix.Tasks.ReleaseKitArtifactTest do
     assert File.regular?(Path.join(out_dir, "release_kit-task-version.tar.gz.sha256"))
     assert File.regular?(Path.join(out_dir, "release_kit.etf"))
 
-    manifest = out_dir |> Path.join("release_kit.etf") |> File.read!() |> :erlang.binary_to_term()
-    assert manifest.target == %{os: "linux", arch: "x86_64", libc: "glibc"}
+    manifest = ReleaseKit.Manifest.read!(Path.join(out_dir, "release_kit.etf"))
+    assert manifest.target == %ReleaseKit.Target{os: "linux", arch: "x86_64", libc: "glibc"}
 
     assert_receive {:mix_shell, :info, ["Release tarball: " <> _]}
     assert_receive {:mix_shell, :info, ["ReleaseKit manifest: " <> _]}

test/release_kit/manifest_test.exs

@@ -3,7 +3,7 @@ defmodule ReleaseKit.ManifestTest do
 
   alias ReleaseKit.Manifest
 
-  test "builds deployment-neutral manifest map" do
+  test "builds typed deployment-neutral manifest" do
     manifest =
       Manifest.new(
         app: "demo_app",
@@ -17,7 +17,7 @@ defmodule ReleaseKit.ManifestTest do
         env_secret: ["SECRET_KEY_BASE"]
       )
 
-    assert Manifest.to_external_map(manifest) == %{
+    assert %Manifest{
              tool: "release_kit",
              format: :beam_release_artifact,
              format_version: 2,
@@ -36,7 +36,7 @@ defmodule ReleaseKit.ManifestTest do
                port: 4000,
                url: "http://127.0.0.1:4000/health"
              }
-           }
+           } = manifest
   end
 
   test "includes artifact, target, build, and asset metadata when provided" do
@@ -68,22 +68,20 @@ defmodule ReleaseKit.ManifestTest do
         ]
       )
 
-    external = Manifest.to_external_map(manifest)
+    assert %ReleaseKit.ArtifactInfo{checksum: %{value: "abc123"}} = manifest.artifact
+    assert %ReleaseKit.Target{os: "linux", arch: "x86_64", libc: "glibc"} = manifest.target
+    assert %ReleaseKit.BuildInfo{git_revision: "abcdef0"} = manifest.build
 
-    assert external.artifact.checksum.value == "abc123"
-    assert external.target == %{os: "linux", arch: "x86_64", libc: "glibc"}
-    assert external.build.git_revision == "abcdef0"
-
-    assert external.assets == [
-             %{
+    assert [
+             %ReleaseKit.AssetInfo{
                tool: :volt,
                profile: :demo_web,
                outdir: "priv/static/assets",
                manifest: "priv/static/assets/manifest.json",
                asset_url_prefix: "/assets",
                tailwind?: true
              }
-           ]
+           ] = manifest.assets
   end
 
   test "writes ETF manifest" do
@@ -103,8 +101,7 @@ defmodule ReleaseKit.ManifestTest do
 
     assert :ok = Manifest.write!(manifest, path)
 
-    loaded = path |> File.read!() |> :erlang.binary_to_term()
-    assert loaded.release == "demo"
-    refute Map.has_key?(loaded, :health_check)
+    loaded = Manifest.read!(path)
+    assert %Manifest{release: "demo", health_check: nil} = loaded
   end
 end