25. Hex package scope is CLI/ACP-only until public Elixir APIs are explicit

Copy Markdown View Source

Date: 2026-06-19 Status: Accepted Implementation status: Accepted package scope for the first Hex release. This ADR defines the distribution contract before and after initial publication.

Context

ADR 0016 intentionally deferred Hex publication. Pixir's source-install beta is now usable for a local operator through the CLI and ACP, but publishing to Hex would create a public distribution contract. That contract is easy to overstate: a Hex package can look like a stable Elixir library even when the intended product surface is an escript and an ACP server.

Pixir already has much of the mechanical Hex metadata in mix.exs: app, version, description, package, licenses, links, docs, dependencies from Hex, and an escript configuration. A local package build also succeeds. The remaining question is not "can Hex build a tarball?" but "what public contract does that tarball imply?"

Decision

1. First Hex scope is CLI/ACP-only. The first Hex package, if published, is a distribution path for installing and running Pixir as a local tool:

mix escript.install hex pixir
pixir doctor --json
pixir acp

It does not promise a stable public Elixir library API.

2. Public API promise stays narrow. The stable surface for a first Hex release is:

  • CLI behavior documented in README and quickstart docs;
  • ACP over stdio;
  • local diagnostics such as pixir doctor --json;
  • documented local file/log behavior and security boundaries.

Internal modules under Pixir.* may be documented for transparency, but are not stable extension points until a later ADR explicitly marks them public.

3. Hex owner is explicit and separate from GitHub. The package owner must be a Hex.pm user or Hex.pm organization, not implicitly a GitHub account. The initial owner is TBD. If the owner starts as an individual Hex user, transfer or additional owner policy must be recorded before a broader release.

4. Package contents must be curated before publishing. The first publication should not rely only on Hex defaults. The package should explicitly include runtime and public documentation files and exclude local agent instructions, scratch artifacts, benchmark state, generated docs, and local runtime state.

5. A GitHub Release binary may still precede Hex. Hex is useful for Elixir-native installation, but it is not the only way to improve operator ergonomics. A prebuilt binary release can remain the lower-API-commitment path if package API boundaries are not ready.

Consequences

  • Hex is no longer blocked on the idea that every Pixir.* module must be stable.
  • The first package can be judged as a CLI/ACP install surface rather than as a library.
  • Docs and ExDoc must clearly say which surfaces are stable and which are internal.
  • mix.exs should get explicit package file curation before publication.
  • Ownership is a release decision, not an accident of whoever runs mix hex.publish.

Non-goals

  • Do not publish in this ADR.
  • Do not claim a stable public Elixir API.
  • Do not imply packaged T3Code integration or an upstream T3 provider.
  • Do not add telemetry, self-update, MCP, web UI, multi-provider support, or SLA promises.
  • Do not treat a successful mix hex.build as sufficient for publication readiness.

Verification Direction

Before any Hex publication, the release candidate should pass:

mix check
mix docs --warnings-as-errors
mix hex.publish --dry-run
mix hex.build --unpack
mix escript.build
./pixir doctor --json

The unpacked package must be inspected for:

  • no local runtime state (.pixir, _build, deps, tmp, generated doc);
  • no local/private agent scaffolding;
  • no secrets or machine-specific paths;
  • expected README, LICENSE, mix.exs, runtime lib, and public docs;
  • install instructions for mix escript.install hex pixir;
  • clear CLI/ACP-only API stability wording.

After publication, test installation in a fresh project/shell:

mix escript.install hex pixir
pixir --version
pixir doctor --json
pixir acp

References