@spec categorize_results([result()]) :: {[result()], [result()], [result()]}

Bucket results into {uninstalled, failed, skipped}. Mirrors MobDev.Deployer.categorize_results/1.

@spec execute_plan(plan()) :: {[result()], [result()], [result()]}

Execute a plan/0 against the connected devices. Returns {uninstalled, failed, skipped} lists of result/0 maps.

@spec filter_devices_by_id([MobDev.Device.t()], [String.t()]) :: [MobDev.Device.t()]

Filter a list of %Device{} by device_ids. When device_ids is empty, return all. When non-empty, match by serial OR name (case- sensitive prefix on serial, exact on either name). Devices not found are dropped silently — the caller is expected to validate user intent.

Used by resolve_devices/1 when the user passes --device foo.

@spec interpret_adb_uninstall(String.t(), non_neg_integer()) ::
  {outcome(), String.t() | nil}

Parse adb uninstall output into an outcome.

Adb's reporting is informal:

• "Success" (sometimes followed by other lines) → :uninstalled
• stderr contains "Failure" with "DELETE_FAILED_INTERNAL_ERROR" and "Unknown package" → :skipped (not installed)
• any other non-zero exit → :error

output is the combined stdout+stderr; exit_code is the process exit status. Returns {outcome, reason} where reason is a short user-facing string (or nil for the success case).

@spec interpret_devicectl_uninstall(String.t(), non_neg_integer()) ::
  {outcome(), String.t() | nil}

Parse xcrun devicectl device uninstall app output into an outcome.

devicectl is more structured than adb but its error reporting still varies by Xcode version. Patterns:

• exit 0 → app actually uninstalled (or wasn't there — devicectl doesn't always distinguish; check the listapps probe if precision matters).
• ContainerLookupErrorDomain → bundle id not installed → :skipped.
• MissingProfileError / NotPaired → device-pairing problem, real error.
• Anything else exit != 0 → :error with trimmed output.

Output is the combined stdout+stderr; exit_code is the process exit status. Returns {outcome, reason}.

Public for regression-testing without a paired physical device.

@spec parse_package_list(String.t()) :: [String.t()]

Parse adb shell pm list packages <prefix> output into a list of package names. Returns names without the package: prefix, sorted for deterministic ordering.

iex> MobDev.Uninstaller.parse_package_list("package:com.example.a\npackage:com.example.b\n")
["com.example.a", "com.example.b"]

iex> MobDev.Uninstaller.parse_package_list("")
[]

iex> MobDev.Uninstaller.parse_package_list("garbage\n")
[]

@spec plan(keyword()) :: {:ok, plan()} | {:error, plan_error(), map()}

Build the (devices × apps) plan without executing it.

The Mix task uses this to render a "what's about to happen" preview and prompt for confirmation before any destructive work runs.

Recognized opts: same as uninstall_all/1.

Returns:

• {:ok, plan} — plan ready to execute. Each pair has at least one device and one bundle id.
• {:error, :no_devices, %{detected: 0}} — no connected devices.
• {:error, :ambiguous_devices, %{detected: N}} — multiple devices connected, no --device or --all-devices flag.
• {:error, :no_matching_devices, %{requested: [...]}} — the user passed --device IDs but none matched.

@spec preview_lines([{MobDev.Device.t(), [String.t()]}]) :: [String.t()]

Build a human-readable preview of the uninstall matrix.

Used by the Mix task to show "what's about to happen" before the destructive step. Lines are colored ANSI (faint/cyan/dim) but the ANSI codes can be stripped for assertion-friendly tests.

@spec select_devices([MobDev.Device.t()], [String.t()], keyword()) :: [
  MobDev.Device.t()
]

Pick the target device set from all connected devices given the user-supplied opts.

Precedence:

1. :device_ids non-empty — match by id, regardless of type (the user typed the id, that's explicit consent).
2. Both :all_devices and :all_physical — every connected device.
3. :all_devices only — emulators/simulators (NEVER physical). The destructive sweep is safe by default; touching a physical device requires explicit --all-physical or --device <id>.
4. :all_physical only — physical devices only.
5. Auto-detect: exactly one NON-physical device → target it. Physical devices are never the auto-target.

Public for testing — the precedence ladder is the safety contract.

@spec uninstall_all(keyword()) :: {[result()], [result()], [result()]}

Top-level orchestration: discover devices, resolve target apps, run the uninstall matrix. Equivalent to plan/1 |> execute_plan/1 but raises on the plan-error cases instead of returning a tuple — useful for tests that just want results without going through the Mix-task layer.

Recognized opts: see plan/1.