@spec adb_available?() :: boolean()

Checks if ADB is available in the system PATH.

@spec command_available?(String.t()) :: boolean()

Checks if a command is available in the system PATH.

@spec compile_regex(String.t(), String.t()) :: Regex.t()

Compiles a regex pattern with the given options.

Centralizes regex compilation to avoid duplicating Regex.compile!/2 calls and provides a single place to handle compilation errors.

Examples

iex> DalaDev.Utils.compile_regex("hello\s+world")
~r/hello\s+world/

@spec ensure_dir(String.t()) :: :ok | {:error, term()}

Ensures a directory exists, creating it if necessary.

Returns :ok on success, {:error, reason} on failure.

@spec format_bytes(non_neg_integer()) :: String.t()

Formats a byte size into a human-readable string.

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

Normalizes CLI arguments so underscored long flags keep working.

OptionParser only recognizes hyphenated long options (--dry-run); passing the documented --dry_run spelling is silently dropped on current Elixir releases. Rewrites every argv token that looks like a flag (starts with --, including --flag=value form) so both spellings parse identically. Non-flag values are passed through.

Examples

iex> DalaDev.Utils.normalize_cli_args(["a.txt", "--on_conflict", "skip"])
["a.txt", "--on-conflict", "skip"]

iex> DalaDev.Utils.normalize_cli_args(["--dry_run=true"])
["--dry-run=true"]

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

Parses ADB devices output into a list of device identifiers.

Expects output from adb devices command.

@spec run_adb_for_device(String.t(), [String.t()], keyword()) ::
  {:ok, String.t()} | {:error, term()}

Runs an ADB command for a specific device with timeout.

Convenience wrapper that prepends -s <serial> to the arguments.

@spec run_adb_with_timeout(
  [String.t()],
  keyword()
) :: {:ok, String.t()} | {:error, term()}

Safely runs ADB with timeout protection.

Runs adb directly (no shell involved), and kills the process if it exceeds the timeout. Works identically on macOS, Linux, and Windows — no external timeout binary required.

Returns {:ok, output} on success, {:error, reason} on failure where reason is trimmed output text or :timeout.

Options

• :timeout - timeout in milliseconds (default: 8000)
• :stderr_to_stdout - whether to merge stderr (default: true)
• :exec - optional 2-arity fun (args, opts) :: {output, exit_code} overriding execution (test seam)