{"id":50968951,"url":"https://github.com/bernardopg/full-upgrade","last_synced_at":"2026-06-18T23:32:43.260Z","repository":{"id":361934958,"uuid":"1256513279","full_name":"bernardopg/full-upgrade","owner":"bernardopg","description":"Orquestrador modular de upgrade para Arch Linux — pacman/AUR, Flatpak, Docker, toolchains, firmware e auditorias doctor num único comando","archived":false,"fork":false,"pushed_at":"2026-06-08T21:30:41.000Z","size":1708,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-08T23:17:07.053Z","etag":null,"topics":["arch-linux","aur","bash","cli","pacman","system-administration","upgrade"],"latest_commit_sha":null,"homepage":"https://github.com/bernardopg/full-upgrade/releases/latest","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bernardopg.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-01T21:09:51.000Z","updated_at":"2026-06-08T21:30:43.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/bernardopg/full-upgrade","commit_stats":null,"previous_names":["bernardopg/full-upgrade"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/bernardopg/full-upgrade","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bernardopg%2Ffull-upgrade","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bernardopg%2Ffull-upgrade/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bernardopg%2Ffull-upgrade/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bernardopg%2Ffull-upgrade/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bernardopg","download_url":"https://codeload.github.com/bernardopg/full-upgrade/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bernardopg%2Ffull-upgrade/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34511617,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-18T02:00:06.871Z","response_time":128,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["arch-linux","aur","bash","cli","pacman","system-administration","upgrade"],"created_at":"2026-06-18T23:32:43.104Z","updated_at":"2026-06-18T23:32:43.242Z","avatar_url":"https://github.com/bernardopg.png","language":"Shell","funding_links":["https://github.com/sponsors/bernardopg","https://ko-fi.com/bernardopg","https://www.buymeacoffee.com/wctwom9emu"],"categories":[],"sub_categories":[],"readme":"\u003c!-- markdownlint-disable MD013 MD033 MD041 --\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"assets/banner.png\" alt=\"full-upgrade — Orquestrador modular de upgrade, manutenção e auditoria para Arch Linux\" width=\"100%\"\u003e\n\n\u003cbr\u003e\n\n\u003ca href=\"https://github.com/bernardopg/full-upgrade/releases/latest\"\u003e\u003cimg src=\"https://img.shields.io/github/v/release/bernardopg/full-upgrade?style=for-the-badge\u0026logo=github\u0026color=1793D1\u0026label=release\" alt=\"release\"\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/bernardopg/full-upgrade/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://img.shields.io/github/actions/workflow/status/bernardopg/full-upgrade/ci.yml?style=for-the-badge\u0026logo=githubactions\u0026logoColor=white\u0026label=CI\" alt=\"CI\"\u003e\u003c/a\u003e\n\u003cimg src=\"https://img.shields.io/badge/shell-bash%204%2B-4EAA25?style=for-the-badge\u0026logo=gnubash\u0026logoColor=white\" alt=\"bash\"\u003e\n\u003cimg src=\"https://img.shields.io/badge/Arch%20Linux-1793D1?style=for-the-badge\u0026logo=archlinux\u0026logoColor=white\" alt=\"Arch Linux\"\u003e\n\u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-MIT-blue?style=for-the-badge\" alt=\"license\"\u003e\u003c/a\u003e\n\n\u003cp\u003e\n  \u003cb\u003eUm comando.\u003c/b\u003e Atualiza sistema, AUR, runtimes, toolchains, containers, firmware\n  e plugins de shell/editor — e ainda audita a saúde da máquina com logs humanos e JSONL.\n\u003c/p\u003e\n\n\u003ca href=\"#instalação\"\u003e\u003cb\u003eInstalação\u003c/b\u003e\u003c/a\u003e ·\n\u003ca href=\"#uso-rápido\"\u003e\u003cb\u003eUso\u003c/b\u003e\u003c/a\u003e ·\n\u003ca href=\"#modos-e-filtros\"\u003e\u003cb\u003eModos\u003c/b\u003e\u003c/a\u003e ·\n\u003ca href=\"#doctor\"\u003e\u003cb\u003eDoctor\u003c/b\u003e\u003c/a\u003e ·\n\u003ca href=\"#configuração\"\u003e\u003cb\u003eConfiguração\u003c/b\u003e\u003c/a\u003e ·\n\u003ca href=\"#contribuindo\"\u003e\u003cb\u003eContribuir\u003c/b\u003e\u003c/a\u003e\n\n\u003c/div\u003e\n\n---\n\n`full-upgrade` foi feito para quem mantém uma estação Arch com muitas camadas:\npacotes oficiais, AUR, Flatpak, Docker, linguagens, CLIs de IA, firmware, shell,\neditor e componentes de desktop. A proposta é simples: um comando, passos\ndeclarados, execução rastreável e um resumo final que mostra o que atualizou, o\nque falhou, o que virou aviso e o que ainda exige ação manual.\n\n```text\nfull-upgrade\n  -\u003e preflight\n  -\u003e snapshot e mirrors\n  -\u003e pacman / AUR\n  -\u003e apps, containers e firmware\n  -\u003e toolchains de linguagem\n  -\u003e shell, editor, Hyprland e CLIs\n  -\u003e limpeza\n  -\u003e doctor\n  -\u003e resumo + log + JSONL\n```\n\n## Destaques\n\n| Área | O que entrega |\n| --- | --- |\n| Execução modular | Entrypoint fino em `full-upgrade.sh`, bibliotecas em `lib/*.sh` e steps por domínio em `lib/steps/*.sh`. |\n| Catálogo técnico | 71 steps declarados com categoria, tags, efeito, timeout, dependências e função de implementação. |\n| Segurança operacional | Lock com `flock`, validação de sudo, keepalive controlado, timeouts por step, dry-run e filtros por categoria. |\n| Arch completo | `pacman`, AUR via `paru`/`yay`, keyring, mirrors, snapshot btrfs, `.pacnew`, órfãos e cache. |\n| Ecossistema do usuário | Flatpak, Snap, Docker, npm, pnpm, pip, pipx, uv, Poetry, Rust, Cargo, Go, .NET, Ruby, ghcup e Arduino. |\n| Desktop e firmware | `fwupd`, `bootctl`, Neovim Lazy/Mason, Oh My Zsh, Hyprland plugins e checks de sessão desktop. |\n| Doctor | Auditorias de reboot pendente, systemd, journal, fwupd security, pacman, boot, rede, SMART/NVMe, Python, JavaScript e CLIs de IA. |\n| Observabilidade | Log completo em texto, eventos JSONL por step, links `latest.log`/`latest.jsonl`, resumo opcional em JSON. |\n\n## Instalação\n\n### Via AUR (Arch Linux)\n\nCom um helper de AUR (`yay`, `paru`):\n\n```bash\nyay -S full-upgrade\n# ou\nparu -S full-upgrade\n```\n\nO pacote AUR instala o executável único em `/usr/bin/full-upgrade`, o exemplo de\nconfiguração em `/usr/share/full-upgrade/config.example` e a licença/documentação\nem `/usr/share/{licenses,doc}/full-upgrade/`. Copie o exemplo para começar:\n\n```bash\nmkdir -p ~/.config/full-upgrade\ncp /usr/share/full-upgrade/config.example ~/.config/full-upgrade/config\n```\n\n### Via script de instalação (qualquer distro com Bash 4.3+)\n\n```bash\ngit clone https://github.com/bernardopg/full-upgrade\ncd full-upgrade\n./install.sh\nfull-upgrade --help\n```\n\nO instalador copia a aplicação para:\n\n| Caminho | Função |\n| --- | --- |\n| `~/.local/share/full-upgrade` | Instalação modular com `full-upgrade.sh`, `lib/`, `steps.d/` e `config.example`. |\n| `~/.local/bin/full-upgrade` | Symlink para o executável. Garanta que `~/.local/bin` esteja no `PATH`. |\n| `~/.config/full-upgrade/config` | Configuração inicial criada a partir de `config.example`, sem sobrescrever arquivo existente. |\n\nTambém é possível gerar um arquivo único:\n\n```bash\n./build.sh\n./dist/full-upgrade-standalone.sh --help\n```\n\n## Atualização\n\nO `full-upgrade` se mantém atualizado sozinho a partir das releases do GitHub:\n\n```bash\nfull-upgrade --version      # mostra a versão instalada\nfull-upgrade --update       # baixa e instala a última release (pede confirmação)\nfull-upgrade --update -y    # atualiza sem perguntar\n```\n\nDurante o fluxo normal, o step **\"Checar atualização do full-upgrade\"** apenas\navisa quando há uma versão nova (não baixa nada) — você decide quando rodar\n`--update`. O canal e a origem são configuráveis:\n\n| Chave | Default | Descrição |\n| --- | --- | --- |\n| `FULL_UPGRADE_REPO` | `bernardopg/full-upgrade` | Repositório `owner/repo` no GitHub. |\n| `FULL_UPGRADE_UPDATE_CHANNEL` | `release` | `release` (última tag) ou `main` (bleeding edge). |\n\nNo canal `release`, o `--update` baixa o **standalone publicado** junto do seu\n`.sha256`, **verifica o SHA-256** e só então instala o binário em\n`~/.local/bin/full-upgrade` (guardando o anterior em `…/full-upgrade.bak`). Se o\nchecksum não bater — download corrompido ou adulterado em trânsito — a\natualização é **abortada antes de qualquer execução**. Requer `curl` e\n`sha256sum`/`shasum`. O canal `main` usa o tarball-fonte + `install.sh` e avisa\nque, nesse caso, a integridade não é verificada por checksum (apenas TLS).\n\n## Uso Rápido\n\n```bash\nfull-upgrade\nfull-upgrade --mode update\nfull-upgrade --mode doctor\nfull-upgrade --mode repair\nfull-upgrade --dry-run\nfull-upgrade --list-steps\nfull-upgrade --explain-step \"Doctor: saúde de rede\"\nfull-upgrade --config\n```\n\nComandos úteis no dia a dia:\n\n| Comando | Quando usar |\n| --- | --- |\n| `full-upgrade` | Fluxo completo: updates, reparos habilitados, limpeza, checks finais e auditorias. |\n| `full-upgrade -y` | Execução não interativa, assumindo confirmações seguras. |\n| `full-upgrade --dry-run` | Ver o plano de execução sem rodar comandos mutáveis. |\n| `full-upgrade --mode update` | Atualizar e limpar, pulando `repair` e `doctor`. |\n| `full-upgrade --mode doctor` | Focar nas auditorias de saúde. O fluxo ainda passa pelo preflight compartilhado. |\n| `full-upgrade --mode repair` | Rodar apenas reparos conhecidos, além dos steps compartilhados necessários. |\n| `full-upgrade --only lang` | Rodar apenas steps de uma categoria ou tag. |\n| `full-upgrade --skip-category slow` | Pular steps marcados com uma tag específica. |\n| `full-upgrade --skip \"Atualizar ghcup\"` | Pular um step pelo nome exato. |\n| `full-upgrade --json` | Imprimir uma linha JSON de resumo ao final. |\n| `full-upgrade --config` | Mostrar caminhos, valores efetivos em uso e um exemplo de configuração. |\n| `full-upgrade --config-example` | Imprimir só o config de exemplo (sem cores), ideal para criar o arquivo via `\u003e`. |\n| `full-upgrade --quiet` | Reduzir output no terminal e manter o detalhe no log. |\n| `full-upgrade --restart-services` | Permitir reinício de serviços apontados por `needrestart`/`checkservices`. |\n\n## Modos e Filtros\n\nO script combina modos formais com filtros de catálogo:\n\n| Modo | Escopo |\n| --- | --- |\n| `full` | Padrão. Executa o fluxo completo disponível no ambiente. |\n| `update` | Updates e limpeza, sem reparos mutáveis opcionais e sem doctor. |\n| `doctor` | Auditorias e checks de saúde, preservando steps compartilhados de preflight/finalização. |\n| `repair` | Reparos conhecidos, sem limpeza. |\n\nFiltros:\n\n```bash\nfull-upgrade --only doctor\nfull-upgrade --only docker\nfull-upgrade --only network\nfull-upgrade --skip-category aur\nfull-upgrade --skip-category cleanup\nFULL_UPGRADE_SKIP=\"Atualizar ghcup,Atualizar gems de usuário\" full-upgrade\n```\n\nCategorias e tags vêm do catálogo. Para descobrir os nomes válidos:\n\n```bash\nfull-upgrade --list-steps\nfull-upgrade --explain-step \"Atualizar pacotes do sistema e AUR\"\n```\n\n## Catálogo de Steps\n\nCada step tem metadados no formato:\n\n```text\nnome | categoria | tags | efeito | timeout | dependências | função | descrição\n```\n\nExemplo:\n\n```text\nDoctor: saúde de rede\nCategoria: doctor\nTags: network,read\nEfeito: read\nTimeout: 30s\nFunção: doctor_network_health\nDescrição: Verifica DNS e conectividade HTTPS para mirrors Arch.\n```\n\nStatus possíveis no resumo:\n\n| Status | Significado | Impacto no exit code |\n| --- | --- | --- |\n| `ok` | Step concluído. | Mantém sucesso. |\n| `warn` | Problema não bloqueante ou falha transitória tratada. | Mantém sucesso. |\n| `todo` | Requer decisão ou ação manual. | Mantém sucesso. |\n| `fail` | Falha operacional real. | Finaliza com exit code `2`. |\n| `skip` | Step pulado por filtro, ausência de dependência, ambiente ou dry-run. | Mantém sucesso. |\n\n## O Que Ele Atualiza\n\n| Domínio | Cobertura principal |\n| --- | --- |\n| Preflight | Lock anti-concorrência, sudo, espaço em `/` e `/boot`, `archlinux-keyring`, backup de configs críticas de `/etc` (`tar.zst` com rotação). |\n| Snapshot e mirrors | `snapper`/`timeshift` em btrfs (com pré-flight de espaço), `reflector`/`rate-mirrors` com backup validado da mirrorlist. |\n| Sistema | `pacman`, AUR, reparos conhecidos de lock, GnuPG/AUR, conflitos locais, limpeza recursiva de órfãos, snapshots antigos do próprio script e `.pacnew/.pacsave`. |\n| Apps | Flatpak e Snap quando presentes. |\n| Containers | Pull de imagens Docker remotas, detecção rápida de daemon inacessível e aviso de containers usando imagem antiga. |\n| Firmware e boot | `fwupdmgr` e `bootctl`. |\n| JavaScript | `npm`, pacotes npm globais, `corepack`, `pnpm` e pacotes pnpm globais. |\n| Python | `pip --user`, `pipx`, `uv`, Python gerenciado pelo uv e Poetry, com proteção contra conflito `poetry-core` fixado pelo Poetry. |\n| Rust | `rustup`, `cargo-install-update` e auditoria com `cargo-audit`. |\n| Outras linguagens | Go, .NET, Ruby gems, ghcup e Arduino CLI. |\n| Shell/editor | Oh My Zsh, plugins customizados de Zsh, Neovim Lazy/Mason e Hyprland `hyprpm`. |\n| CLIs e extras | Claude Code, Hermes, GitHub Copilot, AdGuard VPN, DankMaterialShell, Burp Suite e Wireshark quando habilitados. |\n\nFerramentas ausentes não quebram a execução normal: o step é marcado como\n`skip` com o motivo, e o restante do fluxo continua.\n\n### Salvaguardas recentes de manutenção\n\n- **Órfãos recursivos:** `Remover pacotes orfãos` repete a consulta\n  `pacman -Qdtq` após cada remoção para capturar dependências que só viram\n  órfãs depois da primeira passada. O limite é `ORPHAN_CLEANUP_MAX_ROUNDS`\n  (default `5`); se ainda sobrar item, o step vira `todo`, não `fail`.\n- **Retenção de snapshots:** `Limpar snapshots full-upgrade antigos` remove\n  apenas snapshots cuja descrição contém `full-upgrade pré-upgrade`, mantendo os\n  `SNAPSHOT_KEEP` mais recentes. Não toca snapshots manuais/de outras origens.\n- **Mirrorlist:** quando `reflector` ou `rate-mirrors` falha, o backup só é\n  restaurado se contiver uma linha `Server =` ativa. Backup vazio ou totalmente\n  comentado não sobrescreve a mirrorlist corrente.\n- **Docker:** a checagem inicial usa timeout curto configurável\n  (`DOCKER_INFO_TIMEOUT_S`, default `5`) antes de decidir que o daemon está\n  inacessível. Isso evita runs presos por dezenas de segundos em máquinas com\n  Docker instalado, mas parado ou sem permissão.\n- **Poetry / `poetry-core`:** quando o Poetry instalado declara requisito fixo\n  para `poetry-core`, o update genérico de `pip --user` adiciona `poetry-core`\n  ao ignore efetivo. Isso evita o ping-pong de versão entre o step de pip e o\n  step de Poetry.\n- **Resumo final:** categorias técnicas são renderizadas por grupos estáveis;\n  `flatpak`/`docker`/`snap` aparecem sob **Contêineres**, e `editor`/`shell`\n  compartilham um único bloco **Shell / Editor**. Cada grupo mostra tempo total,\n  o rodapé destaca o top 3 mais lento e `--json` inclui `category_totals` e\n  `slowest_steps`.\n\n## Doctor\n\nO doctor transforma manutenção em diagnóstico acionável. Ele cobre:\n\n| Check | Detecta |\n| --- | --- |\n| Reboot pendente | Kernel, systemd ou microcode atualizados sem reboot. |\n| systemd | Units falhadas no sistema e, quando há sessão/bus disponível, no usuário; se `--user` não puder ser consultado, o doctor registra checagem parcial. |\n| Journal | Erros críticos do boot atual, com agrupamento para reduzir ruído. |\n| Firmware | Resultado de `fwupdmgr security`. |\n| Flatpak | Inconsistências via `flatpak repair --user --dry-run`. |\n| Disco | Uso de espaço e inodes em mounts essenciais. |\n| Boot | Estado do systemd-boot, kernel/initrd e espaço no ESP. |\n| Rede | DNS e HTTPS contra endpoints de mirrors Arch. |\n| Serviços antigos | Serviços usando bibliotecas atualizadas via `needrestart` ou `checkservices`. |\n| Pacman | Arquivos ausentes via `pacman -Qkq`. |\n| ALPM | Hooks com falha no journal do boot atual. |\n| SMART/NVMe | Saúde de discos via `smartctl` e `nvme`. |\n| btrfs | Erros de device acumulados e idade do último scrub em raiz btrfs. |\n| Tempo de boot | Total via `systemd-analyze time` e as 5 piores units (`blame`). |\n| Desktop | Portais, PipeWire, WirePlumber e informações gráficas quando disponíveis. |\n| IA | Versões de `claude`, `copilot` e `hermes`. |\n| Python/JS | Dependências quebradas, venvs ausentes, interpreters inválidos e conflitos npm/pnpm. |\n\n## Logs e Automação\n\nArquivos ficam em:\n\n```text\n~/.cache/system-upgrade/\n  full-upgrade-\u003crun_id\u003e.log\n  full-upgrade-\u003crun_id\u003e.jsonl\n  latest.log -\u003e último log humano\n  latest.jsonl -\u003e último log estruturado\n```\n\nO script mantém os 20 logs mais recentes de cada tipo.\n\nJSONL registra eventos de run e step. Campos importantes:\n\n| Campo | Descrição |\n| --- | --- |\n| `event` | `run_start`, `step`, `run_end` ou `summary`. |\n| `run_id` | Identificador único da execução. |\n| `step` | Nome do step, quando aplicável. |\n| `status` | `ok`, `warn`, `todo`, `fail` ou `skip`. |\n| `duration_seconds` | Duração do step ou do run. |\n| `exit_code` | Código retornado pela função do step. |\n| `category`, `tags`, `effect`, `timeout` | Metadados vindos do catálogo. |\n| `category_totals` | No evento `summary`, totais por grupo do resumo (`ok/warn/todo/fail/skip` + tempo). |\n| `slowest_steps` | No evento `summary`, top 3 steps mais lentos não pulados. |\n| `reboot_recommendation` | No evento `summary`, motivo de reboot destacado quando houver. |\n| `log_file`, `jsonl_file` | Caminhos dos artefatos da execução. |\n\nExemplos:\n\n```bash\ntail -f ~/.cache/system-upgrade/latest.log\njq -c 'select(.event == \"summary\")' ~/.cache/system-upgrade/latest.jsonl\njq -r 'select(.event == \"step\" and .status != \"ok\") | [.status, .step, .reason] | @tsv' ~/.cache/system-upgrade/latest.jsonl\n```\n\n## Configuração\n\nFunciona sem configuração. Para personalizar:\n\n```bash\nmkdir -p ~/.config/full-upgrade\ncp config.example ~/.config/full-upgrade/config\n$EDITOR ~/.config/full-upgrade/config\n```\n\nPara inspecionar o que está em uso (caminhos, valores efetivos após\nconfig + defaults + auto-detecção, listas de ignore e paths de tools), além de\num exemplo completo de configuração:\n\n```bash\nfull-upgrade --config\n```\n\nSem o arquivo ao lado (ex.: instalação via standalone), dá para criar o config a\npartir do exemplo embutido, sem cores:\n\n```bash\nmkdir -p ~/.config/full-upgrade\nfull-upgrade --config-example \u003e ~/.config/full-upgrade/config\n$EDITOR ~/.config/full-upgrade/config\n```\n\nPrincipais chaves:\n\n| Chave | Default | Descrição |\n| --- | --- | --- |\n| `ENABLE_CUSTOM_TOOLS` | `0` | Habilita hooks extras em `steps.d/`. |\n| `LANG_OVERRIDE` | `auto` | Reservado para seleção `auto`, `pt` ou `en`; a saída principal ainda é majoritariamente PT-BR. |\n| `SNAPSHOT_TOOL` | `auto` | `auto`, `snapper`, `timeshift` ou `none`. |\n| `SNAPSHOT_MIN_FREE_GIB` | `2` | Mínimo de espaço livre em `/` para criar o snapshot; abaixo disso o snapshot é pulado com aviso. `0` desliga a checagem. |\n| `SNAPSHOT_KEEP` | `5` | Quantos snapshots `full-upgrade pré-upgrade` manter na limpeza automática. |\n| `MIRROR_TOOL` | `auto` | `auto`, `reflector`, `rate-mirrors` ou `none`. |\n| `MIN_FREE_GIB` | `2` | Espaço mínimo livre em `/`. |\n| `MIN_BOOT_FREE_MIB` | `200` | Espaço mínimo livre em `/boot`. |\n| `BACKUP_CONFIGS` | `1` | Arquiva configs críticas de `/etc` em `tar.zst` antes das mutações. `0` desliga. |\n| `BACKUP_KEEP` | `5` | Quantos tarballs de backup manter (rotação). |\n| `BACKUP_PATHS` | lista de `/etc` | Paths a arquivar, separados por espaço (default cobre `pacman`/boot/`systemd`). |\n| `BTRFS_SCRUB_MAX_DAYS` | `30` | Alerta no doctor se o último scrub btrfs em `/` for mais antigo que isso. |\n| `BOOT_TIME_WARN_S` | `60` | Alerta no doctor se o boot (`systemd-analyze`) exceder N segundos. |\n| `DOCKER_INFO_TIMEOUT_S` | `5` | Timeout curto para detectar daemon Docker inacessível antes de pular o step. |\n| `ORPHAN_CLEANUP_MAX_ROUNDS` | `5` | Rodadas máximas de remoção de órfãos para capturar dependências que viram órfãs após a primeira remoção. |\n| `FULL_UPGRADE_AUR_IGNORE` | vazio | Pacotes AUR ignorados no update automático. |\n| `FULL_UPGRADE_PIP_USER_IGNORE` | vazio | Pacotes `pip --user` ignorados no update genérico. O script ainda adiciona `poetry-core` ao ignore efetivo quando o Poetry instalado fixa uma versão exata. |\n| `GCLOUD_BIN` | auto | Override do binário `gcloud`. |\n| `COPILOT_BIN` | auto | Override do binário `copilot`. |\n| `ADGUARD_BIN` | auto | Override do `adguardvpn-cli`. |\n| `OPENCLAW_BIN` | auto | Override do binário `openclaw`. |\n| `DMS_PLUGINS_DIR` | `~/.config/DankMaterialShell/plugins` | Diretório dos plugins DankMaterialShell. |\n\nComo o arquivo é carregado com `source`, use sintaxe Bash válida.\n\n### Filtro de ruído do journal\n\nO check `Doctor: journal erros críticos` agrupa erros do boot atual e filtra ruído\nconhecido (ex.: falhas HFP do `bluetoothd`). Para silenciar padrões específicos da\nsua máquina, crie `~/.config/full-upgrade/journal-noise.txt` com um regex estendido\n(`grep -E`) por linha; linhas em branco e começando com `#` são ignoradas:\n\n```text\n# um regex-E por linha\ncodeisland\\.service: (Failed at step CHDIR|Changing to the requested)\nftdi_sio .*Unable to read latency timer\n```\n\n## Plugins e Ferramentas Customizadas\n\n`steps.d/` é usado para carregar implementações opcionais de ferramentas que não\ndevem rodar por padrão. O comportamento é propositalmente conservador:\n\n1. `ENABLE_CUSTOM_TOOLS=1` precisa estar definido no config.\n2. Arquivos `.sh` em `~/.config/full-upgrade/steps.d/` e no `steps.d/` instalado são carregados.\n3. As funções carregadas só rodam quando existe um hook correspondente chamado pelo fluxo principal.\n\nExemplos incluídos:\n\n| Arquivo | Hook |\n| --- | --- |\n| `steps.d/10-hermes.sh` | `update_hermes` |\n| `steps.d/20-adguardvpn.sh` | `update_adguardvpn` |\n| `steps.d/30-copilot.sh` | `update_copilot_cli` |\n| `steps.d/40-dms.sh` | `update_dms_plugins` |\n| `steps.d/50-burp-wireshark.sh` | `ensure_security_tools`, reparos de Wireshark e atalhos do Burp |\n\nPara adicionar steps totalmente novos, adicione a função, registre o step em\n`lib/catalog.sh` e chame-o no ponto correto de `lib/main.sh`.\n\n## Requisitos\n\nObrigatórios:\n\n| Requisito | Observação |\n| --- | --- |\n| Arch Linux ou derivado | O fluxo assume `pacman` e convenções de Arch. |\n| Bash 4.3+ | Usa arrays, subscritos negativos e recursos modernos de Bash. |\n| `sudo` | Necessário para steps de sistema. Sem sudo, vários steps serão `skip`. |\n\nOpcionais detectados automaticamente:\n\n```text\nparu, yay, pacman-contrib, reflector, rate-mirrors, snapper, timeshift,\nflatpak, snap, docker, fwupdmgr, bootctl, npm, corepack, pnpm, python, pipx,\nuv, poetry, rustup, cargo, cargo-install-update, cargo-audit, go, dotnet,\ngem, ghcup, arduino-cli, gcloud, claude, hermes, copilot, nvim, hyprpm,\nneedrestart, checkservices, smartctl, nvme, vulkaninfo, glxinfo\n```\n\n## Arquitetura\n\n```text\n.\n├── full-upgrade.sh          # entrypoint: resolve paths, carrega libs e inicia o fluxo\n├── install.sh               # instalação em ~/.local/share + symlink no PATH\n├── build.sh                 # gera dist/full-upgrade-standalone.sh\n├── config.example           # template de configuração do usuário\n├── lib/\n│   ├── globals.sh           # estado global, paths e flags\n│   ├── ui.sh                # cores, símbolos, banner e resumo\n│   ├── core.sh              # helpers, run_step, status e timeouts\n│   ├── json.sh              # log JSONL e rotação\n│   ├── sudo.sh              # validação e keepalive de sudo\n│   ├── config.sh            # XDG config e auto-detecção\n│   ├── catalog.sh           # metadados dos steps e filtros\n│   ├── cli.sh               # flags, modos e saídas precoces\n│   ├── main.sh              # ordem de execução\n│   └── steps/               # implementação por domínio\n└── steps.d/                 # hooks opcionais de ferramentas customizadas\n```\n\nO padrão central é `run_step \"Nome\" funcao`. Ele:\n\n1. aplica `--skip`, `--only`, `--skip-category` e `FULL_UPGRADE_SKIP`;\n2. respeita `--dry-run`;\n3. valida dependências declaradas no catálogo;\n4. aplica timeout por step;\n5. traduz códigos especiais em `warn` e `todo`;\n6. grava log humano e evento JSONL.\n\n## Boas Práticas\n\nAntes de uma execução real:\n\n```bash\nfull-upgrade --dry-run\nfull-upgrade --list-steps\n```\n\nPara manutenção assistida:\n\n```bash\nfull-upgrade --mode update --json\nfull-upgrade --mode doctor --json\n```\n\nPara reduzir risco em automações:\n\n```bash\nfull-upgrade --mode update --no-repair --no-cleanup --json --quiet\n```\n\nPara investigar uma falha:\n\n```bash\ntail -n 120 ~/.cache/system-upgrade/latest.log\njq -r 'select(.event == \"step\" and .status == \"fail\")' ~/.cache/system-upgrade/latest.jsonl\n```\n\n## Troubleshooting\n\n| Sintoma | Diagnóstico provável | Ação |\n| --- | --- | --- |\n| `full-upgrade: diretório lib/ não encontrado` | O symlink não resolve para uma instalação modular válida. | Rode `./install.sh` de novo ou use o standalone gerado por `./build.sh`. |\n| Muitos steps `skip` por sudo | Execução sem TTY, sudo ausente ou credencial indisponível. | Rode em terminal interativo ou ajuste os steps para modo sem sudo. |\n| `--only`/`--skip-category` rejeita categoria | Token não existe no catálogo. | Use `full-upgrade --list-steps` para copiar categoria/tag válida. |\n| Um step demora demais | Timeout por step foi atingido e o status vira `warn`. | Veja `latest.log` e rode `--explain-step` para entender timeout/deps. |\n| JSONL parece incompleto | Execução foi interrompida antes do resumo. | Confira eventos `run_start`, `step` e `run_end` em `latest.jsonl`. |\n| Doctor retorna `todo` | O script encontrou ação manual, não necessariamente uma falha. | Leia o bloco do step no log e decida a correção. |\n\n## Desenvolvimento\n\nValidações rápidas:\n\n```bash\nbash -n full-upgrade.sh install.sh build.sh lib/*.sh lib/steps/*.sh steps.d/*.sh\nshellcheck -S warning -x full-upgrade.sh lib/*.sh lib/steps/*.sh steps.d/*.sh install.sh build.sh\nbats tests/                 # testes unitários (funções puras, sem mutação)\n./full-upgrade.sh --help\n./full-upgrade.sh --list-steps\n./build.sh\n```\n\nAo criar ou alterar steps:\n\n1. mantenha a função no arquivo de domínio em `lib/steps/`;\n2. registre metadados em `lib/catalog.sh`;\n3. chame o step em `lib/main.sh`;\n4. defina timeout realista;\n5. use `RC_WARN` para problema não bloqueante e `RC_TODO` para ação manual;\n6. garanta que dependências ausentes gerem `skip`, não falha desnecessária.\n\n## Apoie o projeto\n\nSe o `full-upgrade` te poupa tempo, considere apoiar o desenvolvimento:\n\n\u003ca href=\"https://github.com/sponsors/bernardopg\"\u003e\u003cimg src=\"https://img.shields.io/badge/GitHub%20Sponsors-EA4AAA?style=for-the-badge\u0026logo=githubsponsors\u0026logoColor=white\" alt=\"GitHub Sponsors\"\u003e\u003c/a\u003e\n\u003ca href=\"https://ko-fi.com/bernardopg\"\u003e\u003cimg src=\"https://img.shields.io/badge/Ko--fi-FF5E5B?style=for-the-badge\u0026logo=ko-fi\u0026logoColor=white\" alt=\"Ko-fi\"\u003e\u003c/a\u003e\n\u003ca href=\"https://www.buymeacoffee.com/wctwom9emu\"\u003e\u003cimg src=\"https://img.shields.io/badge/Buy%20Me%20a%20Coffee-FFDD00?style=for-the-badge\u0026logo=buymeacoffee\u0026logoColor=black\" alt=\"Buy Me a Coffee\"\u003e\u003c/a\u003e\n\n## Contribuindo\n\nContribuições são bem-vindas. Veja [CONTRIBUTING.md](CONTRIBUTING.md) para o\nfluxo de validação e o padrão de steps, e [SECURITY.md](SECURITY.md) para\nreportar vulnerabilidades.\n\n## Licença\n\nMIT. Veja [LICENSE](LICENSE).\n\n\u003cdiv align=\"center\"\u003e\n\u003cbr\u003e\n\u003csub\u003eFeito com ☕ e Bash por \u003ca href=\"https://github.com/bernardopg\"\u003e@bernardopg\u003c/a\u003e · \u003ca href=\"https://github.com/bernardopg/full-upgrade/releases/latest\"\u003eÚltima release\u003c/a\u003e\u003c/sub\u003e\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbernardopg%2Ffull-upgrade","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbernardopg%2Ffull-upgrade","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbernardopg%2Ffull-upgrade/lists"}