Document "mise" usage, decouple from asdf

[adamwight]

Some of the user documentation assumes "asdf" but people might have other tools set up to manage Elixir+Erlang/OTP versions. For example, the Android run_mix script relies on a very particular asdf mechanism and should not do so.

It would be best if the scripts could be robust to choice of tooling. My thinking is that the scripts could detect elixir version to start with. If the version is correct, continue. If it's incorrect, we could try a few of the common mechanisms to set the version and then exit with an error explaining the issue on failure.

[dominicletz]

Yes, we need something more stable there...

[dominicletz]

Feature design: Tooling-agnostic Erlang/Elixir toolchain (mise, asdf, and beyond)

This expands on #67 with a product-consistent plan: document reality without locking developers to one version manager, and make shell automation honest about what it needs (a correct runtime on PATH), instead of encoding asdf-specific paths or behaviors.

---

Problem statement

• User-facing docs (notably the Linux section of Getting your Environment Ready) still read as asdf-first, while many teams use mise, plain PATH installs, kerl, apt packages, or CI images.
• Mobile/build helpers (e.g. Android run_mix in the example-app ecosystem, per the issue) must not depend on asdf-internal mechanics; those break when the tool is absent or when another manager owns .tool-versions.
• Maintainer consensus (comment): we need something more stable than implicit asdf coupling.

---

Fit with the existing product

Elixir Desktop already presents itself as a cross-platform library with platform-specific setup guides (Windows/msys2, macOS/Homebrew, Linux/packages). The natural extension is:

1. Treat .tool-versions as the project contract (asdf file format, already used in this repo and widely understood). It is not “asdf-only”; mise and other tools consume the same file.
2. Keep version managers out of the runtime hot path where possible: after activation, elixir / erl on PATH are what matter.
3. Fail fast with actionable messages, matching the quality bar of the existing guides (explicit prerequisites, copy-paste blocks).

This avoids bolting on a new subsystem; it tightens docs + thin verification around patterns developers already use.

---

User experience principles

Principle	Implication
No vendor lock-in in scripts	Wrapper scripts should invoke mix via whatever runtime is already active, or via explicit, documented opt-ins (mise exec --, asdf exec, direnv, CI image).
Detect, then advise	Prefer: verify the running OTP major + Elixir semver against .tool-versions. If wrong, print what was found, what was expected, and one or two neutral fixes (not “install asdf only”).
Predictable CI	Checks must run in environments with no mise/asdf installed if the image already has the right Erlang/Elixir.
Progressive disclosure	Getting started: short “pick your manager” section; deep links for mise vs asdf examples; keep Erlang Solutions / packages as first-class for Linux.

---

Proposed architecture (two layers)

Layer A — Documentation (human)

• Linux / general: Present mise and asdf side by side for “I want .tool-versions to drive my shell,” with equivalent copy-paste snippets (mise install, asdf install, etc.).
• Explicit rule for shell wrappers: e.g. Android run_mix should use mise exec -- mix … or asdf exec mix … when the developer relies on a manager—never hard-coded shim paths.
• README / FAQ: One sentence pointing to .tool-versions and the verification entry point (below), so discoverability matches “Getting Started → guides.”

Layer B — Machine-checkable verification (optional but recommended)

• A mix desktop.check_toolchain task (or equivalent) that:
  • Reads required erlang / elixir lines from .tool-versions (including OTP “system” style lines where applicable).
  • Compares to System.otp_release/0 and System.version/0 for the currently running BEAM—no shelling out to mise/asdf.
  • Exits non-zero with a clear, copy-paste-friendly remediation block when mismatched.

This matches the direction outlined in PR #68 and keeps CI portable.

Optional Layer C — Script helpers (only if needed)

• Small shared shell functions (sourced by run_mix-style scripts) that:
  1. If mix exists and mix desktop.check_toolchain passes → proceed.
  2. Else try best-effort activation only if the corresponding CLI exists (mise, asdf), then re-check once.
  3. Else exit with the same message as the Mix task.

Strictly optional: many teams prefer “fail unless direnv/CI already set PATH.” Document both patterns.

---

Market / ecosystem alignment

• mise is widely adopted as an asdf-compatible successor; first-class mention reduces friction for new contributors and matches common 2025–2026 Elixir onboarding.
• asdf remains valid; dual documentation avoids alienating existing users.
• Docker / GitHub Actions: verification via mix desktop.check_toolchain after setup-beam (or similar) aligns with standard Elixir CI without extra plugins.

---

Acceptance criteria (definition of done)

1. Docs: No reader-facing path implies “you must use asdf”; Linux (and any other affected sections) present mise + asdf + non-manager options consistent with the rest of the guide’s tone.
2. Scripts: Android/example-app run_mix (and similar) do not rely on asdf-internal paths; they document and use manager-agnostic invocation patterns.
3. Verification: mix desktop.check_toolchain (or agreed equivalent) validates running OTP/Elixir against .tool-versions with tests for parsing edge cases.
4. Errors: Mismatch messages name observed vs expected versions and suggest neutral fixes (activate env, install versions, use CI image).

---

Relation to open work

PR #68 (“Document mise, add tooling-agnostic toolchain check”) implements a large slice of this design. This comment is the issue-level specification so future changes (example-app scripts, FAQ tweaks, optional shell helpers) stay aligned with the same principles.

---

Summary

Deliver a stable contract: .tool-versions declares versions; any activation path is fine; automation verifies the running toolchain instead of assuming asdf. That stays true to Elixir Desktop’s existing guide-driven, multi-platform story without introducing a foreign dependency model.