@spec default_timeout() :: pos_integer()

Default command timeout in milliseconds (30 s).

Used by run_cmd/3 when the caller does not pass :timeout and forwards :timeout to Arrea.Command when it does.

@spec run_cmd(binary(), [binary()], keyword()) ::
  {:ok, binary(), non_neg_integer()} | {:error, Trebejo.Error.t()}

Runs a command via SafeCommand.execute/3, returning {:ok, stdout, exit_code} or {:error, %Trebejo.Error{}}.

This is the single integration point with Arrea so that error handling is consistent everywhere and command names are validated.

Options

All options are forwarded to SafeCommand.execute/3. By default validate is false to maintain backward compatibility with existing callers, timeout is 30 s, and stderr_to_stdout is true. See SafeCommand.execute/3 for details.

@spec run_cmd_legacy(binary(), [binary()], keyword()) :: {binary(), non_neg_integer()}

Like run_cmd/3 but returns the legacy {output, exit_code} tuple that existing call-sites expect. On Arrea failure (timeout, missing binary) returns {"", 1} so callers fall through to their error branch.

Prefer run_cmd/3 for new code.

@spec run_ok(binary(), [binary()], keyword()) :: :ok | {:error, Trebejo.Error.t()}

Runs a command and returns :ok on zero exit or {:error, %Trebejo.Error{}} on any failure.

Like run_cmd/3 but collapses the success branch to :ok and wraps every error path in a %Trebejo.Error{}.

@spec shell_quote(String.t()) :: String.t()

Single-quote a string for safe inclusion in a POSIX shell command.

Replaces internal single quotes with the standard '\'' close-then-reopen pattern.