Formato decidido (decisoes.md). Fase 3 implementada: parse/validação e engine (
internal/recipes), estado (internal/state), retomada por SO (internal/resume) e os comandosrecipeeresume. Falta o smoke em máquina real (WSL e reboot de verdade). Detalhes da engine em arquitetura.md.
Uma receita é uma sequência de etapas para um SO, num arquivo YAML em recipes/<so>/<id>.yaml. Serve
para setups que levam mais de um comando (WSL, ambiente de dev, Office pelo ODT, impressoras) e para
diagnósticos.
id: <id-da-receita> # igual ao nome do arquivo
name: <nome exibido>
description: <uma frase> # opcional
os: windows | linux | macos
kind: setup | diagnostic # padrão: setup
requires_admin: true | false # padrão: false
steps:
- id: <id-da-etapa>
name: <nome exibido> # opcional
check: <ação> # opcional: saiu com 0 = já está feito, etapa pulada
run: <ação> # exatamente um entre run e install
install: [<app>, ...] # ids do catálogo, aceita "python@3.12"
render: <nome> # só diagnóstico, com run: resumo legível da saída (ver "Resumo legível")
reboot: never | required | if-needed # padrão: never
timeout: 30m # opcionalCada check ou run tem exatamente um destes campos:
| Campo | Executa | SO |
|---|---|---|
powershell |
powershell.exe -NoProfile -NonInteractive -EncodedCommand ... |
Windows |
sh |
/bin/sh -c ... |
Linux, macOS |
bash |
bash -c ... |
Linux, macOS |
wsl |
wsl.exe -d <distro> [-u <user>] -- bash -c ... |
Windows |
success_codes aceita exit codes além do 0, por exemplo [3010] para o dism que pede reboot.
PowerShell e exit code. O powershell.exe -EncodedCommand só devolve um exit code diferente de 0 e 1 se o script terminar com exit N; uma expressão booleana (... -eq 'Enabled') sai sempre com 0. Por isso todo check em PowerShell deve terminar com exit 0 / exit 1, e um run com success_codes deve terminar com exit $LASTEXITCODE.
never: nunca reinicia.required: reinicia sempre que a etapa rodar (não reinicia se ela foi pulada pelocheck).if-needed: reinicia só se orunsair com 3010 ou se algum app doinstallpedir reboot.
- Antes de cada etapa, o estado é salvo como
running. Depois, comodone,skippedoufailed. - Quando uma etapa pede reboot, o toolkit, nesta ordem: salva
awaiting-reboot, registra a retomada, pede confirmação (ou segue direto com--yes) e reinicia. Nunca há reboot sem a retomada registrada. - Depois do boot,
toolkit resumecontinua da etapa pendente:- Windows: Tarefa Agendada (
Register-ScheduledTask) no logon do usuário que iniciou a receita, com privilégio elevado quando a receita érequires_admin. O binário é copiado para a pastabindo toolkit antes de registrar. - Linux (segurança): o root do boot só executa e lê o que é de root. O binário é COPIADO para
/usr/local/lib/toolkit/toolkit(root:root 0755), nunca o~/.local/binde quem iniciou a receita; ostate.jsone o log têm de ficar em/var/lib(ou/var/log). O binário é lido uma vez e entregue por stdin, com SHA-256 conferido na cópia e de novo antes doenable; ostate.jsone os diretórios até/var/libtêm de ser de root (uid 0, sem escrita de grupo/outros). Fora disso o registro é recusado (ErrUnsafeRootPath) antes de qualquer comando, e a máquina não reinicia: receita com reboot no Linux exige rodar comsudo. - Linux: unit systemd de sistema (
toolkit-resume.service), oneshot, no boot e depois denetwork-online.target, comConditionPathExistsnostate.jsoneProtectHome=true. Roda como root e sem terminal (toolkit resume --no-tui); sem--yesum reboot novo é recusado e a receita espera o próximo boot. O resultado fica no log e emtoolkit recipe status. Caminhos com espaço não são aceitos. - macOS: LaunchAgent do usuário (
RunAtLoad,LaunchOnlyOnce), que abre o Terminal com um.commandpara mostrar o progresso. Só no login: não é no boot. - Nomes: a tarefa agendada e o label do launchd usam
dev.pilutech.<name>.
- Windows: Tarefa Agendada (
- Ao terminar, com sucesso ou falha, o registro de retomada é removido.
Proteções:
- Se o
resumerodar sem que a máquina tenha reiniciado de fato (o boot ID não mudou), nada avança. - Cada etapa tem 1 tentativa depois da retomada. Se o
checkfalhar depois do reboot, ou a etapa falhar, a receita para, desregistra a retomada e reporta. Não há segundo reboot.toolkit recipe reset <id>libera uma nova tentativa manual. - Se o usuário recusar o reboot, a retomada continua registrada e a receita fica
awaiting-reboot. Ela continua no próximo boot (Linux) ou logon (Windows e macOS). - Se o YAML da receita mudar entre os boots (binário atualizado), a retomada para em vez de continuar uma receita diferente.
- Uma etapa que ficou
running(queda de energia) só é repetida se tivercheck. Semcheck, ela virafailede pede intervenção.
Onde fica o estado:
| SO | Admin/root | Usuário |
|---|---|---|
| Windows | %ProgramData%\toolkit\state.json |
— |
| Linux | /var/lib/toolkit/state.json |
$XDG_STATE_HOME/toolkit/state.json |
| macOS | /Library/Application Support/toolkit/ |
~/Library/Application Support/toolkit/ |
O log de cada execução (logs/<receita>-<data>.log, permissão 0600) fica ao lado do estado e guarda só
eventos (etapa, código de saída, erro), nunca a saída dos comandos. --verbose também o mostra no terminal.
toolkit recipe status lê o estado do privilégio atual (admin ou usuário).
- Windows: receita
requires_adminexige terminal elevado (o relançamento automático com UAC ainda não existe). O toolkit descobre a elevação perguntando ao PowerShell. - Linux: a retomada roda como root e lê
/var/lib/toolkit. Por isso uma receita que pode reiniciar (rebootdiferente denever) tem de ser iniciada comsudo. Receita sem reboot roda como usuário e usasudo -nsó nos comandos de uma receitarequires_admin. - macOS: tudo como usuário (o brew não roda como root).
Só os check rodam (leitura, nunca elevados); o resto é descrito. Não cria estado, log nem retomada e
nunca reinicia. Um check precisa ser só leitura: o dry-run o executa de verdade.
toolkit recipe list [--os windows|linux|macos] [--json]
toolkit recipe run wsl-dev [--yes] [--dry-run] [--verbose]
toolkit recipe status [--json]
toolkit recipe reset wsl-dev # descarta o andamento: libera uma nova tentativa depois de uma falha
toolkit resume [--yes] [--verbose] [--no-tui]É a recipes/windows/wsl-dev.yaml embutida no binário (resumida aqui). Repare que cada check em
PowerShell termina com exit 0 / exit 1, e que o run com success_codes termina com exit $reboot.
id: wsl-dev
name: Ambiente WSL + Ubuntu para dev
os: windows
requires_admin: true
steps:
- id: enable-features
check: { powershell: "if ((Get-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform).State -eq 'Enabled') { exit 0 } else { exit 1 }" }
run:
powershell: |-
$reboot = 0
foreach ($f in 'VirtualMachinePlatform', 'Microsoft-Windows-Subsystem-Linux') {
dism /online /enable-feature /featurename:$f /all /norestart
if ($LASTEXITCODE -eq 3010) { $reboot = 3010 }
elseif ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
}
exit $reboot
success_codes: [3010]
reboot: if-needed
- id: install-distro
check: { powershell: "if (wsl -l -q | Select-String -Quiet Ubuntu) { exit 0 } else { exit 1 }" }
run: { powershell: "wsl --install -d Ubuntu --no-launch" }
- id: apps
install: [git, vscode]A etapa setup-inside (rodar o unix.sh da mesma versão dentro da distro, com hash conferido) entra
junto com os bootstraps, na fase 6.
id: linux-dev
name: Ferramentas de dev no Linux
os: linux
steps:
- id: apps
install: [git, python@3.12]
- id: git-defaults
check: { sh: "git config --global init.defaultBranch" }
run: { sh: "git config --global init.defaultBranch main" }Diagnósticos são receitas com kind: diagnostic, sem reboot. A saída de cada etapa vai para o relatório
mostrado na aba Diagnóstico.
id: diag-memoria
name: Diagnóstico de memória
os: windows
kind: diagnostic
steps:
- id: modulos
run: { powershell: "Get-CimInstance Win32_PhysicalMemory | Select-Object Manufacturer,PartNumber,Capacity,Speed | Format-Table -AutoSize" }
- id: disco
run: { powershell: "Get-PhysicalDisk | Select-Object FriendlyName,MediaType,HealthStatus,OperationalStatus | Format-Table -AutoSize" }Uma etapa de diagnóstico pode ter render: <nome>: a saída crua do comando (JSON do PowerShell, /proc/meminfo,
system_profiler...) passa por um renderizador de internal/diagfmt e o relatório mostra um resumo em pt-BR, ou em
en/es por TOOLKIT_LANG, LC_ALL, LC_MESSAGES ou LANG (o primeiro valor não vazio decide; outro idioma cai em
pt-BR). A saída original só aparece no modo detalhes: tecla e na aba Diagnóstico da TUI (o d é "desfazer" em toda a TUI; a dica mostra
e detalhes ✓ quando ligado; vale para os diagnósticos marcados na próxima execução) ou toolkit recipe run <id> --detalhes; ela vem depois do resumo, sob -- Detalhes (saída original) --. Nada é mascarado: o resumo, os detalhes e a saída de uma
falha do comando mostram o que o sistema informou, como veio (o toolkit é uma ferramenta de análise). Se o renderizador não entender a saída (formato novo do sistema), a etapa NÃO falha, mas a
saída crua NÃO aparece por padrão: só o aviso "não deu para resumir esta saída; use --detalhes, ou a tecla d na TUI, para ver a original". O render
só vale em etapa run de receita kind: diagnostic; um nome desconhecido é erro de carga. Renderizadores:
| Nome | Entrada | Resumo |
|---|---|---|
windows-memory |
JSON de Win32_PhysicalMemory, Win32_PhysicalMemoryArray e Win32_OperatingSystem |
Memória: 8 GB no total (1 de 2 slots usados) · DDR4 2400 MT/s, um Slot N por módulo (capacidade · fabricante · peça) e Em uso agora: 5,1 de 7,9 GB (65%) |
windows-disks |
JSON de Get-PhysicalDisk |
Disco: LITEON CV8-CE256-HP · SSD · 256 GB · saudável (Healthy = saudável, Warning = atenção, Unhealthy = com problema) |
linux-memory |
linhas de /proc/meminfo |
total, em uso (total menos MemAvailable) e swap; os pentes exigem root e não são mostrados |
linux-disks |
JSON de lsblk -b -d -J |
uma linha por disco (SSD/HDD/NVMe e tamanho); a saúde SMART exige root e não é verificada |
macos-memory |
sysctl hw.memsize, vm_stat e system_profiler SPMemoryDataType |
total, tipo quando o macOS informa, em uso aproximado |
macos-disks |
system_profiler (NVMe, SATA, armazenamento) |
Disco: <modelo> · SSD · 500 GB · S.M.A.R.T.: verificado |
Capacidade de memória usa GB binário (8589934592 bytes = 8 GB, como o Windows mostra) e a de disco, GB decimal (como o
fabricante anuncia); decimais com vírgula em pt-BR e es e com ponto em en. Fabricante da RAM no Windows vem de uma tabela de
códigos JEDEC comuns (80AD SK hynix, 80CE Samsung, 802C Micron, 859B Crucial, 0198 Kingston, 029E Corsair, 04CB A-DATA, 04EF Team Group,
04CD G.Skill, 830B Nanya); um código fora da tabela aparece como JEDEC <código> exatamente como veio (só o preenchimento
provado de 16 dígitos, código de 4 mais 12 zeros, é descartado; 8010 nunca vira 0801). O tipo da RAM vem do SMBIOSMemoryType
(DSP0134, Type 17: 20 é DDR2 FB-DIMM, 21 a 23 são reservados) e, só quando ele vem 0, do MemoryType legado do WMI (20 é DDR):
são tabelas diferentes e não se misturam. No macOS o disco é identificado pelo nome BSD (disk0): a mesma identidade em
duas seções do system_profiler vira um disco (vale o pior status SMART) e dois discos do mesmo modelo continuam dois;
a visão de volumes (Storage) só se junta a um disco NVMe/SATA com identidade FÍSICA comprovada: o disco inteiro do volume
(disk0s2 é do disk0) ou, para volume de contêiner APFS (disk3s5, do contêiner disk3), o disco físico do contêiner
pelo mapa do diskutil apfs list -plist (a receita emite as seções ### profiler e ### apfs: disk3 -> disk0s2 ->
disk0). Ter o MESMO MODELO nunca prova nada (um externo igual ao interno é outro disco). Sem prova o volume vira disco
próprio, um por disco físico (disk6s1 e disk6s2 são do disk6; disk6 e disk7 são dois), e sem bsd_name fica
sozinho. O mapa APFS é um complemento OPCIONAL: o diskutil só entra na seção ### apfs quando termina com sucesso (ausente
ou com erro, a seção sai vazia, a etapa NÃO falha e o resumo sai só com o profiler; só a falha do system_profiler é a falha
da etapa). O plist é lido com XML estrito (precisa fechar </plist> e terminar: truncado, mesmo depois de um dict completo, não
vale). Sem o mapa um volume de contêiner não se junta a ninguém e o disco interno pode aparecer também como disco do Storage. As receitas continuam só de leitura e sem
administrador. Cada etapa do Log da TUI sai como ✓ Memória (no lugar de etapa modulos: done).
Testes: internal/diagfmt/*_test.go (saídas falsas: código JEDEC desconhecido, slot vazio, 2+ módulos, formatos truncados,
en/es), internal/recipes/render_test.go (engine: resumo, detalhes, idioma, renderizador que falha) e
internal/recipes/diagmemoria_real_test.go, que roda a etapa de verdade (só leitura) no runner e confere que o renderizador
entende a saída real (no Windows isto acontece no CI, no windows-latest).
toolkit recipe run diag-rede (ou a aba Diagnóstico da TUI). Só leitura: nada de sudo, nada que mude rede, DNS,
firewall ou rotas, nada gravado em arquivo. Cinco etapas, cada uma com saída resumida:
| Etapa | Linux | macOS |
|---|---|---|
interfaces |
ip -brief address, estado e MTU (ip -o link), rota padrão (IPv4 e IPv6) |
ifconfig -a (estado, MTU e endereços das interfaces com endereço), route -n get default |
dns |
servidores em uso (resolvectl status ou /etc/resolv.conf) e resolução de um nome (getent, host ou nslookup) |
servidores do scutil --dns (sem os resolvedores com escopo) e resolução por dscacheutil |
alcance |
ping ao gateway e a um alvo, e uma requisição HTTPS (curl) com tempos de TCP, TLS e total |
o mesmo (ping -t 6) |
wifi |
adaptador e sinal/canal/taxa pelo NetworkManager (nmcli); sem NetworkManager, avisa e segue |
adaptador e energia (networksetup); o nome da rede não aparece |
portas |
portas TCP em escuta (ss -ltn) |
portas TCP em escuta (netstat -an -p tcp) |
Alvos externos (variáveis de ambiente, todas opcionais; o valor é validado e um valor inválido é recusado na etapa sem chamar nada):
| Variável | Padrão | Aceita |
|---|---|---|
TOOLKIT_DIAG_HOST |
1.1.1.1 |
letras, dígitos, ., :, _, -; nunca começa com - |
TOOLKIT_DIAG_NAME |
example.com |
letras, dígitos, ., _, -; nunca começa com - |
TOOLKIT_DIAG_URL |
https://example.com/ |
só https://, com host e caminho em letras, dígitos e . _ ~ : / - |
O curl roda como env -u SSLKEYLOGFILE curl -q ...: o -q (primeiro argumento) impede a leitura da .curlrc do usuário
(que poderia mandar corpo, Authorization, request, gravar cookie-jar ou trace) e a variável de chave TLS não
chega a ele; só segue redirecionamentos para https (--proto-redir =https), no máximo 3, com --connect-timeout 5 e
--max-time 10. O corpo da resposta é descartado. O nslookup (último recurso no Linux) roda com HOME=/, sem ler o
~/.nslookuprc; ping, ip, ss, getent, nmcli, route e netstat não leem configuração do usuário.
Informações como o sistema informa. Nada é mascarado: IPs (públicos inclusive), IPv6 global, gateway, servidores DNS, as respostas da resolução de nomes, as caudas de erro do ping e do curl e o nome da rede Wi-Fi (SSID) aparecem inteiros. As portas aparecem sem endereço (só "só esta máquina" ou "toda a rede") por ficarem mais legíveis, e o MAC não é coletado (a receita não o pede); não há consulta de "meu IP público".
Idioma. A saída sai em pt-BR por padrão e em en ou es por TOOLKIT_LANG, LC_ALL, LC_MESSAGES ou LANG
(nessa ordem; pt_BR, en_US, es_ES... e qualquer outro idioma cai em pt-BR). Cada etapa tem um bloco
case "$lang" com as mesmas chaves m_* nos três idiomas (um teste confere que as chaves são idênticas e que toda
$m_x usada está traduzida). O nome e a descrição da receita no YAML ainda são só pt-BR (o formato de receita não tem
campo de idioma; ver docs/auditoria-a11y-l10n.md, L5).
Limites. Um diagnóstico nunca falha por causa do achado: rede fora do ar, ping sem resposta ou falta de uma
ferramenta aparecem na saída (falhou, "o comando 'x' não existe") e a etapa termina com status 0. No macOS o
sistema pode dizer "sem conexão" quando a permissão de Localização não foi dada (o nome da rede vem do networksetup). A
diag-rede do Windows é mais simples (adaptadores, endereços e DNS) e ainda não aceita alvos.
Testes (internal/recipes/diagrede_test.go, sem rede real): validação do YAML por plataforma; lista de comandos
proibidos (nada de sudo, escrita de rede, redirecionamento para arquivo); sintaxe sh -n; chaves de idioma; e a
execução de cada etapa em /bin/sh com um PATH que só tem ferramentas de texto reais e ip, ping, curl,
networksetup etc. FALSAS, que registram cada chamada (toda chamada tem de estar na lista de leitura permitida):
IPs e SSID sem máscara, idioma, alvos configurados, alvos inválidos recusados, falha de rede sem erro e ausência de
ferramentas. Os testes dos scripts não rodam no Windows.
- Nada de
curl | bashde terceiros. Scripts só do próprio repositório, na versão do binário em execução e com hash conferido. - Nada que ative ou contorne licenciamento.
- Prefira
install:(catálogo) a baixar instalador norun. Se precisar baixar, use um appurlougithub-releaseno catálogo, que exige hash. - Toda etapa que altera o sistema deve ter
check, para a receita ser idempotente e a retomada segura.