The contract a plugin implements.

A plugin installs one infrastructure concern into a generated project — a cache, a container runtime, a vault, an auth stack — and knows nothing about what the project is for. Most of a plugin is data: the files it owns, the dependencies it needs, the capabilities it requires and provides. Only two callbacks are code, and both are escape hatches.

This behaviour is public and stable from day one because a plugin may live in a separate repository and must install without editing SvEx's source (R4).

Defining a plugin

defmodule MyOrg.Valkey do
  use SvEx.Plugin.Behavior, name: :valkey, version: "1.3.0"

  @impl true
  def files(_config) do
    [
      {"lib/APP/cache.ex", :sole_owner},
      {"compose.yaml", :contributes, key: :valkey_service}
    ]
  end

  @impl true
  def deps, do: [{:nebulex, "~> 3.0"}]

  @impl true
  def requires, do: [:container_runtime]
end

name/0 and version/0 come from the use options. files/1 must be implemented. deps/0, requires/0, provides/0 and conflicts/0 default to [] and are overridable. transform/2 and upgrade/3 are optional.

Why so little of it is code

deps/0 is a declared list rather than something read back out of the plugin's own mix.exs (D10). A plugin that reflects its own project copies in_umbrella: true and path deps straight into the target and breaks it.

Everything a plugin returns must be deterministic — the same inputs must produce the same bytes today and in eighteen months, because an update regenerates a historical version and diffs it (D8). No timestamps, no randomness, no map iteration order leaking into output.

The two escape hatches, and how they must fail

transform/2 and upgrade/3 exist for what the file list cannot express. Both must let exceptions propagate. Never wrap the body in a bare rescue.

This is not style. Fireside swallowed exceptions from its equivalents in a bare rescue and bumped the recorded version anyway, so a transform that did nothing was recorded as having succeeded — the manifest became a claim rather than a fact. SvEx records a version only after every step actually succeeded (G5), and that is only true if failure is loud.