@spec add_flags(
  args(),
  keyword()
) :: args()

Appends new_flags to the args config. Use from Marea.Plugins.Base.marea_config_args/1.

@spec add_options(
  args(),
  keyword()
) :: args()

Appends new_options to the args config. Use from Marea.Plugins.Base.marea_config_args/1.

@spec add_subcommands(
  args(),
  keyword()
) :: args()

Adds new_subcommands to the args config. Use from Marea.Plugins.Base.marea_config_args/1.

Merges by key so multiple plugins can extend the same parent subcommand (e.g. Marea.Plugins.Docker and Marea.Plugins.Helm both contribute children under build). For an already-present parent, the new entry's :subcommands / :options / :flags are appended, and other keys (:name, :about, …) keep the first writer's value. Top-level entries that don't yet exist are appended at the end.

@spec base_args() :: args()

Returns the base args config map that plugins enrich via Marea.Plugins.Base.marea_config_args/1.

Includes the global --marea-dir, --state-dir, --help, --nopause options/flags, and an empty subcommands list.

@spec build_args_tree([module()]) :: args()

Runs the Marea.Plugins.Base.marea_config_args/1 chain on a list of plugin modules, returning the accumulated args map.

Unlike Malla.local/3, this does not require a running Malla.Service: every plugin's marea_config_args/1 is a plain function generated by defcb, so we can fold over them directly. Used by the MCP server to expose tool descriptors without spinning up the full service.

All marea_config_args/1 implementations are expected to return {:cont, [args]}; any other shape is ignored (matching the default in Marea.Plugins.Base).

@spec build_optimus(args()) :: Optimus.t()

Builds an Optimus parser from the final (plugin-enriched) args config.

@spec cookie_option() :: spec()

Reusable spec for the --cookie option (defaults to marea_cookie).

@spec deploy_option() :: spec()

Reusable spec for the --deploy / -d option.

@spec mix_env_option(String.t() | nil) :: spec()

Reusable spec for --mix-env. If default is given, it is used when the option is missing.

@spec parse!(Optimus.t(), [String.t()]) :: {[atom()], map(), map()} | no_return()

Parses args against optimus, returning {cmds, options, flags}.

Normalizes --help/-h placement so that marea aws --help becomes marea help aws, and aborts with a clear error on unknown options or parse failures.

@spec pos_option() :: spec()

Reusable spec for --pos (integer; used to run multiple instances side-by-side).

@spec release_option() :: spec()

Reusable spec for the --release / -r option.