Helpers para plugins
O MB CLI injeta no ambiente dos plugins a variável MB_HELPERS_PATH, que aponta para o diretório dos helpers de shell (ex.: ~/.config/mb/lib/shell no Linux; ~/Library/Application Support/mb/lib/shell no macOS).
Os ficheiros são criados/atualizados pelo mb plugins sync. Se ainda não existirem, execute o sync antes.
Referência rápida
| Helper | O que faz | Plataforma |
|---|---|---|
log | Log com níveis (info, warn, error…) respeitando -q/-v | Todas |
context | Lê variáveis MB_CTX_* da invocação do plugin | Todas |
string | Manipulação de texto (replace, case, trim, bool) | Todas |
memory | Memória chave/valor entre execuções (ficheiros em tmp) | Todas |
os | Detecção de OS e distro Linux | Todas |
mbcli-yaml | Lê/escreve mbcli.yaml do projeto | Todas |
sudo | Validação de privilégio (warn_and_skip_without_sudo) | Todas |
ensure | Pré-requisitos de CLI (ensure_yq, etc.) | Todas |
shell-rc | Blocos geridos em ~/.config/mb/shell-extras.sh + stub mínimo em .bashrc/.zshrc | Todas |
kubernetes | Operações básicas com kubectl | Todas |
snap | Instalar/atualizar apps via Snap Store | Linux |
homebrew | Instalar/atualizar casks e fórmulas | macOS |
flatpak | Instalar/atualizar apps via Flatpak | Linux |
github | Buscar versões, baixar releases do GitHub | Todas |
Como carregar
Carregue todos de uma vez ou individualmente:
# Todos os helpers (recomendado para plugins complexos)
. "$MB_HELPERS_PATH/all.sh"
# Helpers individuais
. "$MB_HELPERS_PATH/log.sh"
. "$MB_HELPERS_PATH/os.sh"
Core
log
Log com níveis respeitando MB_QUIET e MB_VERBOSE (flags -q e -v). Usa gum log -l internamente.
Uso: log <level> <mensagem...>
Níveis: none, debug, info, warn, error, fatal, output, print
| Condição | Comportamento |
|---|---|
MB_QUIET=1 | Só error e fatal |
MB_VERBOSE=1 | Todos os níveis, incluindo debug |
| Normal | info, warn, error, fatal, output, print (sem debug) |
MB_LOG_OUTPUT set | Todas as chamadas vão ao gum com nível none (saída "pura") |
log info "Processando..."
log debug "Detalhe interno: $var"
log warn "Aviso"
log error "Algo falhou"
log print "=> Passo visível sem prefixo de nível"
context
Funções que leem as variáveis MB_CTX_* injetadas pelo runtime do CLI. O significado de cada variável está em Contexto de invocação de plugins.
Funções principais:
| Função | O que faz |
|---|---|
mb_context_dump | Imprime pares MB_CTX_* (uma linha por variável) |
mb_context_dump_json | Imite um objeto JSON com todo o contexto (usa jq ou python3) |
mb_peer_commands_lines | Lista comandos irmãos (um por linha) |
mb_child_commands_lines / mb_hidden_child_commands_lines | Lista comandos filhos visíveis/ocultos |
mb_child_command_info_json | Imprime MB_CTX_CHILD_COMMAND_INFO (JSON [{name,description},…]; ausente → []) |
mb_ctx_has_plugin_flag <flag> | Exit 0 se flag está em MB_CTX_PLUGIN_FLAGS |
mb_ctx_peer_contains <nome> | Exit 0 se <nome> é comando irmão |
mb_ctx_child_contains / mb_ctx_hidden_child_contains | Idem para filhos visíveis/ocultos |
mb_ctx_peer_count / mb_ctx_child_count / mb_ctx_hidden_child_count | Imprime contagem (inteiro) |
mb_ctx_parent_is <path> | Exit 0 se parent command path é exatamente <path> |
mb_ctx_command_path_is <path> | Exit 0 se command path é exatamente <path> |
mb_ctx_path_depth | Imprime número de segmentos do command path |
mb_ctx_cache_db | Imprime caminho do cache.db |
# Depuração rápida
. "$MB_HELPERS_PATH/context.sh"
mb_context_dump
# Iterar sobre comandos irmãos
. "$MB_HELPERS_PATH/all.sh"
while IFS= read -r peer; do
[[ -z "$peer" ]] && continue
log info "Outro comando neste grupo: $peer"
done < <(mb_peer_commands_lines)
string
Manipulação de texto em shell.
| Função | Descrição |
|---|---|
str_replace <input> <search> <replace> | Substitui todas as ocorrências |
str_to_upper <texto> / str_to_lower <texto> | Converte case |
str_trim <texto> | Remove espaços no início e fim |
str_contains <texto> <substring> | Exit 0 se contém |
str_starts_with <texto> <prefixo> | Exit 0 se começa com |
str_parse_comma_separated <nome_array> | Divide elementos com vírgula no array |
str_join_to_comma_separated <nome_array> | Junta elementos com vírgula |
str_to_bool <valor> | Exit 0 para true, 1, on, yes |
. "$MB_HELPERS_PATH/string.sh"
tag=$(str_to_lower "$(str_trim " My-App ")")
if str_starts_with "$tag" "my"; then
log info "Tag começa com 'my'"
fi
if str_to_bool "${DRY_RUN:-false}"; then
log warn "Dry-run ativo"
fi
memory
Memória chave/valor entre execuções. Dados guardados em ${TMPDIR:-/tmp}/mb/memory/<namespace>/<key>.
| Função | Descrição |
|---|---|
mem_set <namespace> <key> <valor...> | Cria ou atualiza |
mem_get <namespace> <key> [default] | Lê (ou retorna default) |
mem_has <namespace> <key> | Exit 0 se existe |
mem_unset <namespace> <key> | Remove |
mem_clear_ns <namespace> | Limpa todo o namespace |
Dados em tmp podem ser removidos pelo sistema (reboot/limpeza).
. "$MB_HELPERS_PATH/memory.sh"
if ! mem_has "tools.deploy" "cluster"; then
cluster="$(gum input --placeholder "Nome do cluster")"
mem_set "tools.deploy" "cluster" "$cluster"
fi
cluster="$(mem_get "tools.deploy" "cluster" "dev")"
log info "Usando cluster: $cluster"
Configuração de projeto
mbcli-yaml
Lê e altera o ficheiro mbcli.yaml na raiz do projeto. Depende de yq (Mike Farah v4); use ensure_yq ou carregue all.sh.
Resolução do caminho: MBCLI_YAML_PATH → ${MBCLI_PROJECT_ROOT}/mbcli.yaml → ${PWD}/mbcli.yaml.
| Variável | Valores | Efeito |
|---|---|---|
MBCLI_YAML_ON_MISSING | error (default) / ignore | Com ignore, get sem ficheiro retorna exit 0 e stdout vazio |
MBCLI_YAML_AUTOCREATE | 0 (default) / 1 | Com 1, set e ensure criam o ficheiro ({}) se não existir |
| Função | Descrição |
|---|---|
mbcli_yaml_path | Imprime caminho resolvido do YAML |
mbcli_yaml_ensure | Garante que o ficheiro existe (com AUTOCREATE=1) |
mbcli_yaml_get <expressão_yq> | Avalia expressão e imprime JSON |
mbcli_yaml_set <caminho_yq> <valor...> | Atribui valor ao caminho (usa strenv) |
mbcli_yaml_del <caminho_yq> | Remove o nó |
. "$MB_HELPERS_PATH/all.sh"
export MBCLI_PROJECT_ROOT="${MBCLI_PROJECT_ROOT:-$PWD}"
export MBCLI_YAML_AUTOCREATE=1
export MBCLI_YAML_ON_MISSING=error
mbcli_yaml_ensure
mbcli_yaml_set '.example.version' '1.0.0'
ver="$(mbcli_yaml_get '.example.version' | jq -r .)"
log info "Versão em mbcli.yaml: $ver"
O CLI também lê a chave envs no mbcli.yaml e mescla no ambiente do subprocesso. Veja Variáveis de ambiente.
Utilitários
os
Detecção de sistema operacional e distribuição Linux.
| Função | Descrição |
|---|---|
get_simple_os | linux, mac ou unknown |
is_mac / is_linux | Exit 0 se for o OS |
is_linux_debian / is_linux_redhat / is_linux_arch | Exit 0 se distro |
get_debian_pkg_manager | apt-get ou apt |
get_redhat_pkg_manager | dnf ou yum |
get_arch_pkg_manager | pacman ou unknown |
get_distro_id | $ID de /etc/os-release |
. "$MB_HELPERS_PATH/os.sh"
if is_linux_debian; then
sudo "$(get_debian_pkg_manager)" install -y curl
elif is_mac; then
brew install curl
fi
sudo
Validação de privilégio para operações que precisam de sudo.
| Função | Descrição |
|---|---|
is_root | Exit 0 se EUID=0 ou sudo -n sem prompt |
warn_and_skip_without_sudo [nome] | Aviso PT-BR no stderr + exit 86 se sem root/sudo non-root |
check_sudo [msg] | Igual a is_root; em falha, log warn e exit 1 |
required_sudo [--optional] [ctx] | Executa sudo -v; com --optional segue sem abortar |
# Uso típico no início de install_linux / update_linux:
warn_and_skip_without_sudo "Redis CLI" || return $?
# Garantir privilégio (pode pedir senha):
required_sudo
Código 86 = MB_EXIT_UPDATE_SKIPPED_SUDO: sem privilégio para apt/dnf/etc. No batch --update-all, não é falha; o pai avisa para repetir com sudo.
ensure
Pré-requisitos de CLI. Cada função loga erro e faz exit 1 se o comando não estiver no PATH.
| Função | O que verifica |
|---|---|
ensure_npx | npx (Node.js) |
ensure_jq | jq |
ensure_yq | yq (Mike Farah v4) |
ensure_gum | gum |
ensure_fzf | fzf |
ensure_kubectl | kubectl |
shell-rc
Blocos idempotentes com marcadores # mb-cli-plugins:<tool>:begin / :end. O corpo vive em ${XDG_CONFIG_HOME:-$HOME/.config}/mb/shell-extras.sh; se ~/.bashrc e/ou ~/.zshrc já existirem, acrescenta-se um stub (uma linha de source desse ficheiro) quando ainda não estiver presente. Não cria ~/.bashrc / ~/.zshrc automaticamente.
Se o mesmo marcador ainda existir só nos RCs (instalação antiga), na próxima shell_rc_ensure_block o bloco é removido dali e passa a existir só em shell-extras.sh (sem duplicar init).
| Função | Descrição |
|---|---|
shell_rc_extras_path | Imprime o caminho de shell-extras.sh |
shell_rc_touch_extras_file | Cria o directório mb e o ficheiro inicial se faltar |
shell_rc_ensure_stub | Garante a linha source de shell-extras.sh nos RC existentes |
shell_rc_ensure_block MARKER_BEGIN MARKER_END BODY | Garante stub + ficheiro extras; acrescenta o bloco em shell-extras.sh (migra legado dos RCs se necessário) |
shell_rc_remove_block MARKER_BEGIN MARKER_END | Remove o bloco de shell-extras.sh e dos RCs (limpeza legada) |
Package managers
snap (Linux)
Instalar, atualizar e remover apps via Snap Store. Requer sudo para instalação/atualização/remoção.
| Função | Descrição |
|---|---|
snap_is_available | Exit 0 se snap no PATH |
snap_is_installed <app> | Exit 0 se aparece em snap list |
snap_get_installed_version <app> | Versão instalada ou unknown |
snap_get_latest_version <app> | Versão publicada ou unknown |
snap_install <app> [friendly] [channel] [classic] | Instala (com --classic se classic=true) |
snap_update <app> [friendly] [channel] | Atualiza se versão diferente |
snap_uninstall <app> [friendly] | Remove com --purge |
snap_refresh_metadata | snap refresh --list (non-fatal) |
snap_info <app> / snap_list_installed | Info bruta / lista todos |
homebrew (macOS)
Casks e fórmulas via Homebrew.
| Função | Descrição |
|---|---|
homebrew_is_available | Exit 0 se brew no PATH |
homebrew_is_installed <cask> / homebrew_is_installed_formula <formula> | Verifica instalação |
homebrew_get_installed_version <cask> / homebrew_get_installed_version_formula <formula> | Versão ou unknown |
homebrew_get_latest_version <cask> / homebrew_get_latest_version_formula <formula> | Última versão ou unknown |
homebrew_install <cask> [friendly] / homebrew_install_formula <formula> [friendly] | Instala |
homebrew_update <cask> [friendly] / homebrew_update_formula <formula> [friendly] | Atualiza |
homebrew_uninstall <cask> [friendly] / homebrew_uninstall_formula <formula> [friendly] | Remove (--zap para casks) |
homebrew_link_formula <formula> [force] | Cria links simbólicos |
flatpak (Linux)
Instalar e gerenciar apps via Flatpak/Flathub.
Em Linux, se o comando flatpak não existir, flatpak_ensure_flathub (e portanto flatpak_install) tenta instalar o motor via pacotes de sistema: Debian/Ubuntu e derivados (apt/apt-get: flatpak e, em seguida, gnome-software-plugin-flatpak — este último é opcional e falhas silenciosam com log debug se o pacote não existir); Fedora/RHEL e derivados (dnf ou yum: flatpak). É necessário sudo (required_sudo). Em Arch ou outras distros não cobertas, mantém-se apenas a mensagem e o link flatpak.org/setup. Em macOS o helper não instala Flatpak nem configura Flathub (flatpak_ensure_flathub devolve sucesso sem efeito).
O remoto Flathub é adicionado ao nível utilizador (flatpak remote-add --user) com o URL https://dl.flathub.org/repo/flathub.flatpakrepo.
| Função | Descrição |
|---|---|
flatpak_is_available | Exit 0 se flatpak no PATH |
flatpak_bootstrap_host_linux | Instala o pacote flatpak no host (Debian ou RHEL) quando o CLI falta; no-op em macOS |
flatpak_ensure_flathub | Garante motor (bootstrap em distros suportadas) e repositório Flathub --user |
flatpak_is_installed <app_id> | Exit 0 se instalado |
flatpak_get_installed_version <app_id> / flatpak_get_latest_version <app_id> | Versão ou unknown |
flatpak_install <app_id> [friendly] | Instala do Flathub |
flatpak_update <app_id> [friendly] | Atualiza |
flatpak_uninstall <app_id> [friendly] | Remove com dados |
Integrações externas
kubernetes
Operações básicas com kubectl. Carrega log.sh automaticamente.
| Função | Descrição |
|---|---|
kb_check_installed [exit_on_error] | Exit 0 se kubectl no PATH |
kb_check_namespace_exists <ns> [exit_on_error] | Exit 0 se namespace existe |
kb_get_current_context | Nome do contexto ativo |
kb_print_current_context | Imprime contexto legível |
github
Buscar versões, baixar e instalar releases do GitHub. Carrega log.sh automaticamente.
Dependências: curl (obrigatório), jq (opcional), tar (para extração).
| Função | Descrição |
|---|---|
github_get_latest_version <owner/repo> [strip_prefix] | Tag da última release |
github_get_latest_version_with_fallback <o/r> [branch] [path] [field] | API → raw fallback |
github_detect_os_arch [format] | os:arch do sistema |
github_build_download_url <o/r> <ver> <os> <arch> <pattern> | Monta URL com substituições |
github_download_release <url> <output> [desc] | Baixa com progresso |
github_download_and_verify <o/r> <ver> <url> <out> <cksum> [alg] | Baixa + verifica checksum |
github_extract_tarball <tar> [dir] | Extrai e imprime diretório |
github_install_binary <dir> <name> <install_dir> | Localiza e instala binário |
github_install_release <o/r> <ver> <name> <dir> <pattern> [cksum] [alg] | Pipeline completo |