🎯 Funcionalidades do Susa CLI¶

Guia completo das funcionalidades do Susa CLI

📋 Índice¶

Visão Geral
Conceitos Chave
Descoberta Automática
Categorias e Subcategorias
Filtragem por SO
Sistema de Plugins
Bibliotecas
Referência Rápida

🎯 Visão Geral¶

O Susa CLI é um framework modular e extensível para criar ferramentas de linha de comando em Bash. O Susa usa descoberta automática e configurações descentralizadas.

✨ Características Principais¶

Funcionalidade	Descrição
🔍 Descoberta Automática	Comandos descobertos da estrutura de diretórios
📄 Config Descentralizada	Cada comando tem seu próprio `command.json` e cada categoria seu `category.json`
🌍 Multi-plataforma	Suporte para Linux e macOS
📂 Subcategorias	Hierarquia de comandos ilimitada
🔌 Plugins	Extensão via Git sem modificar código
📦 Bibliotecas	Logger, OS detection, JSON parser, etc
📖 Help Customizado	Documentação por comando

🚀 Caso de Uso Ideal¶

✅ DevOps: Automatizar instalações e configurações
✅ Administração: Gerenciar servidores e ambientes
✅ Desenvolvimento: Scripts de setup e deploy
✅ Equipes: Padronizar workflows

💡 Conceitos Chave¶

🎯 Descoberta Automática¶

O CLI descobre comandos automaticamente da estrutura de diretórios:

# Criar nova pasta = novo comando disponível
mkdir -p commands/setup/docker
cat > commands/setup/docker/command.json << EOF
name: "Docker"
description: "Instala Docker Engine"
entrypoint: "main.sh"
EOF

# Comando já está disponível!
susa setup docker

📄 Configuração Descentralizada¶

Cada comando tem seu próprio command.json e cada categoria seu category.json:

{
  "name": "Docker",
  "description": "Instala Docker Engine",
  "entrypoint": "main.sh",
  "sudo": false,
  "os": ["linux", "mac"]
}

📂 Hierarquia de Comandos¶

commands/
  setup/                 # Categoria
  ├── asdf/              # Comando
  │   ├── category.json
  │   └── main.sh
  └── python/            # Subcategoria
      ├── category.json
      └── pip/           # Comando
          ├── category.json
          └── main.sh

🔍 Descoberta Automática¶

Como Funciona¶

O sistema varre diretórios em 3 etapas:

1. Scanner de Diretórios¶

Procura em:

📁 commands/ - Comandos nativos
📁 plugins/*/ - Comandos de plugins

2. Detecção de Tipo¶

Condição	Tipo	Resultado
Tem `command.json` + campo `entrypoint` + arquivo existe	Comando	Executável
Tem `category.json` sem entrypoint	Categoria	Navegável
Sem arquivo de configuração	Ignorado	-

3. Disponibilização Imediata¶

Comandos ficam disponíveis automaticamente:

mkdir -p commands/deploy/production
cat > commands/deploy/production/command.json << EOF
name: "Production"
description: "Deploy para produção"
entrypoint: "main.sh"
EOF

echo '#!/bin/bash\necho "Deploying..."' > commands/deploy/production/main.sh
chmod +x commands/deploy/production/main.sh

# Já funciona!
susa deploy production

Vantagens¶

✅ Sem JSON centralizado
✅ Cada comando é independente
✅ Fácil adicionar/remover (apenas pasta)
✅ Plugins não modificam arquivos centrais

📂 Categorias e Subcategorias¶

Navegação Hierárquica¶

# Ver categorias
susa
# Output: self, setup

# Ver comandos da categoria
susa setup
# Output: asdf, ...

# Navegar subcategoria
susa setup python
# Output: pip, venv, ...

# Executar comando
susa setup python pip

Estrutura Exemplo¶

commands/
├── setup/               # Categoria
│   ├── category.json
│   ├── asdf/            # Comando
│   │   ├── category.json
│   │   └── main.sh
│   └── python/          # Subcategoria
│       ├── category.json
│       └── pip/         # Comando
│           ├── command.json
│           └── main.sh
└── self/                # Categoria
    ├── category.json
    ├── version/         # Comando
    │   ├── category.json
    │   └── main.sh
    └── plugin/          # Subcategoria
        ├── category.json
        ├── add/         # Comando
        │   ├── category.json
        │   └── main.sh
        └── list/        # Comando
            ├── category.json
            └── main.sh

Boas Práticas¶

Mantenha 2-3 níveis de profundidade
Use nomes descritivos e curtos
Agrupe comandos relacionados
Cada nível pode ter arquivos de configuração (command.json ou category.json) com metadados

Para mais detalhes, veja Guia de Subcategorias.

🌍 Filtragem por SO¶

Como Funciona¶

O campo os no command.json filtra comandos automaticamente:

// Apenas Linux
{ "os": ["linux"] }

// Apenas macOS
{ "os": ["mac"] }

// Ambos
{ "os": ["linux", "mac"] }

// Omitir = todos os SOs

Exemplos¶

// commands/setup/apt/command.json
{
  "name": "APT Tools",
  "description": "Ferramentas APT (Ubuntu/Debian)",
  "entrypoint": "main.sh",
  "os": ["linux"]
}

// commands/setup/brew/command.json
{
  "name": "Homebrew",
  "description": "Gerenciador de pacotes",
  "entrypoint": "main.sh",
  "os": ["mac"]
}

Detecção de SO¶

O CLI detecta automaticamente:

linux - Detecta distribuições Linux
mac - Detecta macOS

Validação¶

Antes de executar

Se o comando é compatível com o SO atual
Se tem permissões necessárias (sudo)
Se dependências existem

🔌 Sistema de Plugins¶

Plugins estendem o CLI via repositórios Git.

Instalação¶

# Usando URL completa
susa self plugin add https://github.com/usuario/plugin

# Usando formato user/repo
susa self plugin add usuario/plugin

Estrutura de Plugin¶

meu-plugin/
├── categoria1/
│   ├── category.json
│   └── comando1/
│       ├── category.json
│       └── main.sh
└── categoria2/
    ├── category.json
    └── comando2/
        ├── category.json
        └── main.sh

Gerenciamento¶

# Listar plugins
susa self plugin list

# Atualizar plugin
susa self plugin update nome-plugin

# Remover plugin
susa self plugin remove nome-plugin

Vantagens¶

✅ Não modifica código principal
✅ Comandos disponíveis imediatamente
✅ Atualizações independentes
✅ Fácil compartilhamento

Para mais detalhes, veja:

📦 Bibliotecas Disponíveis¶

O Susa CLI oferece bibliotecas úteis em lib/:

Logger (`lib/logger.sh`)¶

log_info "Informação"
log_success "Sucesso"
log_warning "Aviso"
log_error "Erro"
log_debug "Debug (só com DEBUG=true)"

Colors (`lib/color.sh`)¶

echo -e "${LIGHT_GREEN}Verde${NC}"
echo -e "${LIGHT_CYAN}Ciano${NC}"
echo -e "${RED}Vermelho${NC}"
echo -e "${BOLD}Negrito${NC}"

Shell (`lib/shell.sh`)¶

detect_shell_type        # Detecta bash, zsh, fish
get_completion_status    # Status do autocompletar

OS (`lib/os.sh`)¶

detect_os                # Detecta Linux, macOS
get_os_release_info      # Info da distribuição

Para documentação completa, veja Referência de Bibliotecas.

🎯 Referência Rápida¶

Estrutura de Arquivos¶

// cli.json (raiz)
{
  "name": "Susa CLI",
  "description": "Gerenciador de Shell Scripts",
  "version": "1.0.0",
  "commands_dir": "commands",
  "plugins_dir": "plugins"
}

// commands/categoria/category.json
{
  "name": "Setup",
  "description": "Instalar e configurar ferramentas"
}

// commands/categoria/comando/command.json
{
  "name": "ASDF",
  "description": "Instala ASDF",
  "entrypoint": "main.sh",
  "sudo": false,
  "os": ["linux", "mac"]
}

Template de Comando¶

#!/bin/bash
set -euo pipefail


show_help() {
    show_description
    echo ""
    show_usage
    echo ""
    echo -e "${LIGHT_GREEN}Opções:${NC}"
    echo "  -h, --help    Mostra ajuda"
}

install() {
    log_info "Instalando..."
    # Código aqui
    log_success "Instalado!"
}

# Parse argumentos
while [[ $# -gt 0 ]]; do
    case "$1" in
        --help|-h)
            show_help
            exit 0
            ;;
        *)
            log_error "Opção desconhecida: $1"
            exit 1
            ;;
    esac
done

install

Comandos Úteis¶

# Listar categorias
susa

# Listar comandos
susa setup

# Executar comando
susa setup asdf

# Ver ajuda
susa setup asdf --help

# Debug
DEBUG=true susa setup asdf

# Plugins
susa self plugin list
susa self plugin add user/plugin
susa self plugin update plugin
susa self plugin remove plugin

# Informações
susa self version
susa self info
susa self update

📚 Próximos Passos¶

Adicionar Comandos - Como criar comandos
Configuração - Personalizar o CLI
Shell Completion - Autocompletar
Subcategorias - Hierarquia de comandos
Sistema de Plugins - Criar plugins

🎯 Funcionalidades do Susa CLI¶

📋 Índice¶

🎯 Visão Geral¶

✨ Características Principais¶

🚀 Caso de Uso Ideal¶

💡 Conceitos Chave¶

🎯 Descoberta Automática¶

📄 Configuração Descentralizada¶

📂 Hierarquia de Comandos¶

🔍 Descoberta Automática¶

Como Funciona¶

1. Scanner de Diretórios¶

2. Detecção de Tipo¶

3. Disponibilização Imediata¶

Vantagens¶

📂 Categorias e Subcategorias¶

Navegação Hierárquica¶

Estrutura Exemplo¶

Boas Práticas¶

🌍 Filtragem por SO¶

Como Funciona¶

Exemplos¶

Detecção de SO¶

Validação¶

🔌 Sistema de Plugins¶

Instalação¶

Estrutura de Plugin¶

Gerenciamento¶

Vantagens¶

📦 Bibliotecas Disponíveis¶

Logger (lib/logger.sh)¶

Colors (lib/color.sh)¶

Shell (lib/shell.sh)¶

OS (lib/os.sh)¶

🎯 Referência Rápida¶

Estrutura de Arquivos¶

Template de Comando¶

Comandos Úteis¶

📚 Próximos Passos¶

Logger (`lib/logger.sh`)¶

Colors (`lib/color.sh`)¶

Shell (`lib/shell.sh`)¶

OS (`lib/os.sh`)¶