🧹 Limpando projetos automaticamente com PowerShell

Script PowerShell para apagar lixos desnecessários (por exemplo node_modules, .next, target, bin/obj) em árvores de projetos, com base em stacks que escolhe no assistente. Tudo o que precisa de distribuir está num único ficheiro: clean-projects.ps1. O ficheiro clean-projects.config.json só é criado depois de correr -Configure e guarda raízes, stacks e a lista fechada de nomes de pastas permitidas.

Requisitos

Windows com PowerShell 5.1 ou superior (#requires -Version 5.1).
Permissões de leitura/escrita nas pastas que pretende limpar.
Para -Schedule: módulo ScheduledTasks (normalmente presente no Windows).

Instalação

Copie a pasta clean-projects (ou apenas clean-projects.ps1) para um sítio fixo, por exemplo:
- %USERPROFILE%\tools\clean-projects\
Não mova o .ps1 à ligeira depois de criar a tarefa agendada: a tarefa guarda o caminho completo do script. Se mover, volte a correr -Schedule.

Política de execução

Se o script for bloqueado:

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

Ou execute uma vez com:

powershell.exe -NoProfile -ExecutionPolicy Bypass -File "C:\caminho\completo\clean-projects.ps1" -Configure

(Substitua pelo caminho real do ficheiro.)

UTF-8 com BOM (importante se editar o `.ps1`)

O ficheiro deve estar guardado em UTF-8 com BOM para o Windows PowerShell 5.1 interpretar corretamente caracteres acentuados no código. Se regravar o script num editor que remove o BOM e surgirem erros de sintaxe estranhos, volte a gravar como UTF-8 with BOM.

Ficheiros

Ficheiro	Descrição
`clean-projects.ps1`	Script único: catálogo de stacks embutido, lógica de limpeza e agendamento.
`clean-projects.config.json`	Gerado por `-Configure`. Não edite à mão salvo que saiba o que faz.

Primeira configuração

Na pasta do script (ou com caminho absoluto):

.\clean-projects.ps1 -Configure

O assistente pede:

Stacks — números separados por vírgula (ex.: 1,3,5) ou all para todas as listadas em -ListStacks.
Pastas raiz — uma por linha; linha vazia termina. São diretórios onde o script procura recursivamente por pastas com nome exatamente igual a um dos nomes permitidos (ver JSON abaixo).

No fim é gravado clean-projects.config.json na mesma pasta do .ps1 (salvo que use -ConfigPath).

Parâmetros

Parâmetro	Descrição
`-Configure`	Assistente interativo; gera/atualiza o JSON de configuração.
`-DryRun`	Lista as pastas que seriam removidas; não apaga nada.
`-Schedule`	Cria ou atualiza uma tarefa no Agendador de Tarefas do Windows (pede data/hora, recorrência e confirmação `Y`/`N`).
`-ListStacks`	Mostra o catálogo embutido (`id` e nome).
`-ConfigPath`	Caminho alternativo para `clean-projects.config.json` (predefinição: pasta do script + `clean-projects.config.json`).
`-MaxDepth`	Profundidade máxima de pastas a percorrer (predefinição no JSON, tipicamente `40`; o parâmetro do script pode sobrepor na execução).

Nota: -Configure, -Schedule e a execução normal de limpeza são modos mutuamente exclusivos (conjuntos de parâmetros diferentes).

Uso após configurar

Simular (recomendado antes da primeira limpeza real):

.\clean-projects.ps1 -DryRun

Limpar de facto:

.\clean-projects.ps1

Com config noutro sítio:

.\clean-projects.ps1 -ConfigPath "D:\configs\meu-clean.json"

Listar stacks disponíveis:

.\clean-projects.ps1 -ListStacks

Agendamento no Windows

.\clean-projects.ps1 -Schedule

Pede data e hora da primeira execução (vários formatos são aceites, por exemplo 2026-04-20 09:00 ou 20/04/2026 09:00).
Pede recorrência: uma vez, diária, semanal (dia da semana em inglês, ex.: Monday) ou mensal (dia do mês 1–31).
Mostra um resumo e só regista a tarefa se confirmar com Y (ou S).

Nome da tarefa: CleanProjects_User.

A tarefa executa:

powershell.exe -NoProfile -ExecutionPolicy Bypass -WindowStyle Hidden -File "<script.ps1>" -ConfigPath "<config.json>"

Se falhar o registo, pode precisar de permissões diferentes ou de criar a tarefa manualmente no Agendador. Tarefas para o próprio utilizador costumam funcionar sem administrador; cenários mais restritos podem exigir elevação.

Formato de `clean-projects.config.json` (versão 2)

Exemplo ilustrativo (caminhos e listas reais vêm do -Configure):

{
  "version": 2,
  "scanRoots": ["C:\\dev\\repos"],
  "stackIds": ["node", "next"],
  "allowedFolderNames": [".next", "node_modules", "out", "..."],
  "globalExcludes": [".git", ".svn", ".hg"],
  "maxDepth": 40
}

Campo	Significado
`version`	Versão do esquema (atualmente `2`).
`scanRoots`	Lista de pastas raiz a varrer.
`stackIds`	Stacks escolhidas no assistente (referência; a limpeza usa sobretudo `allowedFolderNames`).
`allowedFolderNames`	Nomes de diretórios (apenas o último segmento do caminho) que podem ser apagados se encontrados sob `scanRoots`.
`globalExcludes`	Nomes de pasta em que o script não entra (não varre conteúdo).
`maxDepth`	Limite de profundidade na árvore.

Se existir uma config antiga só com stackIds e sem allowedFolderNames, o script tenta derivar os nomes a partir do catálogo embutido no .ps1.

Comportamento e segurança

Só remove diretórios cujo nome final está em allowedFolderNames (ou derivado das stacks).
Não segue junctions/symlinks (reparse points): evita seguir ligações para fora da árvore prevista.
Não desce em subárvores cujo nome está em globalExcludes (por defeito .git, .svn, .hg).
Use sempre -DryRun antes de confiar na lista de pastas e raízes.

Alias `clean-projects` no PowerShell

Edite o perfil:

notepad $PROFILE

Se o ficheiro não existir, o PowerShell indica o caminho; pode criar com New-Item -Path $PROFILE -ItemType File -Force.

Adicione (ajuste o caminho absoluto do .ps1):

function clean-projects {
    & 'C:\Users\luizfilipeschaeffer\tools\clean-projects\clean-projects.ps1' @args
}

Recarregue o perfil:

. $PROFILE

Exemplos:

clean-projects -ListStacks
clean-projects -Configure
clean-projects -DryRun

Resolução de problemas

Problema	O que fazer
“cannot be loaded because running scripts is disabled”	`Set-ExecutionPolicy -Scope CurrentUser RemoteSigned` ou use `-ExecutionPolicy Bypass` como nos exemplos.
Config não encontrada	Corra `-Configure` primeiro ou passe `-ConfigPath` correto.
`-Schedule` não cria a tarefa	Verifique mensagem de erro; confirme que o script está guardado em disco com caminho fixo e que tem sessão/utilizador adequado.
Erros estranhos de sintaxe após editar o `.ps1`	Regrave o ficheiro como UTF-8 with BOM.

link do script

Licença / uso

Uso local à sua máquina e à sua responsabilidade: confirme com -DryRun e mantenha cópias de segurança de dados importantes.