# `NBPR.Artifact`
[🔗](https://github.com/jimsynz/nbpr/blob/v0.2.0/lib/nbpr/artifact.ex#L1)

Cache-key, naming, and on-disk layout for NBPR package artefacts.

An nbpr artefact is a tarball produced by source-building a Buildroot
package against a specific (system, system-version, build-options) tuple.
This module is the single source of truth for:

- the canonical cache key derived from those inputs
- the canonical tarball filename
- the local cache directory where the extracted tree lives

Tarball layout (matches `Nerves.Artifact.Archive`'s `--strip-components=1`
contract so we can reuse its extractor later):

    <package>-<version>-<system>-<system_version>/
      manifest.json
      target/         # rootfs overlay
      staging/        # sysroot overlay (optional)
      legal-info/

All functions here are pure. I/O lives in `Mix.Tasks.Nbpr.Fetch` and the
resolver implementations.

# `build_inputs`

```elixir
@type build_inputs() :: %{
  package_name: String.t(),
  package_version: String.t(),
  system_app: atom(),
  system_version: String.t(),
  build_opts: keyword()
}
```

# `cache_dir`

```elixir
@spec cache_dir(build_inputs()) :: String.t()
```

Returns the absolute path to the extracted artefact directory under the
Nerves data dir. Mirrors `Nerves.Env.data_dir/0`'s behaviour: respects
`NERVES_ARTIFACTS_DIR`, falls back to `$XDG_DATA_HOME/nerves`, then
`~/.local/share/nerves`.

# `cache_key`

```elixir
@spec cache_key(build_inputs()) :: String.t()
```

Returns a 16-character hex digest derived from a SHA-256 over the canonical
encoding of all inputs. The encoding sorts `build_opts` so that opt order
doesn't perturb the key.

# `dir_name`

```elixir
@spec dir_name(build_inputs()) :: String.t()
```

Returns the directory name (no leading path) where the extracted artefact
will live. This is also the single top-level directory expected inside the
tarball.

# `download_path`

```elixir
@spec download_path(build_inputs()) :: String.t()
```

Returns the absolute path where the downloaded tarball is staged before
extraction. Sibling to the artefacts dir, mirroring Nerves' `dl/` convention.

# `manifest`

```elixir
@spec manifest(build_inputs()) :: map()
```

Returns a JSON-serialisable map describing the artefact for inclusion as
`manifest.json` inside the tarball. Lets consumers verify that an extracted
artefact matches the cache key they expected.

# `tarball_name`

```elixir
@spec tarball_name(build_inputs()) :: String.t()
```

Returns the canonical tarball filename for a given set of build inputs.

    "nbpr_jq-0.1.0-nerves_system_rpi4-1.30.0-<key>.tar.gz"

---

*Consult [api-reference.md](api-reference.md) for complete listing*