Automação de Compressão de Imagens

O que Automação de Compressão de Imagens faz?

Visão Geral

Redimensione e comprima imagens de produtos em lote para arquivos .jpg, .webp ou .avif prontos para a web em segundos usando sharp, preservando nomes de arquivo originais, achatando PNGs transparentes sobre fundo branco e respeitando rigorosamente as proporções (redimensionamento automático por altura única de 800px ou verificação exata LxH).

Princípio fundamental: Nunca assumir uma unidade de trabalho (F:\), nunca recorrer silenciosamente a 800x800 ou jpg sem confirmação quando omitido, e nunca cortar ou distorcer uma imagem.

Referência Rápida

Situação	Ação
Primeira execução (node_modules/ ausente)	Execute npm install (requer Node.js >= 20.0.0)
.imagerc.json ausente e nenhum --dir fornecido	Pergunte ao usuário qual é a pasta de trabalho antes de executar
Tamanho/altura ou formato alvo omitido	Pergunte ao usuário o tamanho (800px de altura ou LxH) e formato (jpg, webp ou avif) antes de executar
Usuário fornece apenas altura (ex.: 800px em webp)	Passe --size 800px --format webp (calcula automaticamente a largura proporcional por imagem)
Usuário fornece pasta de trabalho + LxH + formato	Execute `node bin/cli.js --dir "" --size "" --format <jpg
Usuário tem pastas separadas de raw e exportação	Execute `node bin/cli.js --input "" --output "" --size "<px
Incompatibilidade de proporção exata LxH	Não cortar/esticar; reportar tamanhos correspondentes sugeridos da saída (ou sugerir modo de altura 800px se apropriado)
Fundo PNG transparente	Automaticamente achatado sobre #ffffff (altere via --bg "#hex")

Fluxo de Trabalho Passo a Passo para o Agente

Siga estes passos em ordem sempre que um usuário solicitar compressão ou redimensionamento de imagens usando este repositório:

1. Verificar Configuração e Dependências

1. Verifique se node_modules/sharp existe. Se for um clone novo, execute npm install.
2. Verifique se .imagerc.json existe na raiz do repositório (a menos que o usuário já tenha especificado uma pasta em sua solicitação).
   • Se nem .imagerc.json existir nem o usuário nomeou uma pasta, pergunte ao usuário primeiro: "Qual pasta você gostaria de usar para suas pastas de imagens de entrada e saída? (Por exemplo, ./ para esta pasta do projeto, ~/Desktop/store-images, ou D:\Images.)"
   • Nunca assuma F:\Image Compress Automation ou adivinhe ~/Desktop.

2. Inspecionar input/ e Confirmar Tamanho + Formato

1. Certifique-se de que <pasta>/input e <pasta>/output existam (ou passe --dir "<pasta>" para que o CLI as crie).
2. Verifique quantas imagens suportadas (.png, .jpg, .jpeg, .webp, .avif) estão na pasta de entrada. Se 0, informe ao usuário o caminho exato <pasta>/input para ele colocar suas imagens e pare.
3. Se o usuário não declarou explicitamente a altura/dimensões alvo ou formato de saída na solicitação atual, pergunte antes de executar — mesmo que os fallbacks não-TTY/sem flags padrão sejam 800x800 e jpg.

3. Executar de Forma Não Interativa e Relatar Resultados

Execute o CLI explicitamente com flags (evite node bin/cli.js puro em shells de ferramentas não-TTY para que nada dependa de padrões silenciosos):

node bin/cli.js --dir "<pasta-de-trabalho>" --size "<ALTURAPX ou LARGURAxALTURA>" --format "<jpg|webp|avif>"

Flags opcionais quando solicitadas pelo usuário:

• --format <jpg|webp|avif> (padrão jpg; webp é ~25–35% menor, avif é ~30–50% menor)
• --quality <1-100> (padrão 85 para JPG mozjpeg / WebP effort: 6, e 65 para AVIF effort: 4)
• --bg "<#hex>" (padrão #ffffff para achatamento de PNG transparente)
• --strict (retorna código de saída 1 se qualquer arquivo for ignorado ou falhar)

Se o usuário quiser que esta pasta de trabalho seja lembrada para execuções interativas em terminal (npm start), você pode mencionar ou salvar .imagerc.json (ignorado pelo git) ou fazer com que ele execute npm run setup.

4. Verificar e Resumir a Saída

Relate diretamente a partir da saída do comando:

• Contagens totais de convertidos / ignorados / com falha e espaço economizado (MB e %).
• Caminho exato da pasta de saída (<pasta-de-trabalho>/output).
• Para qualquer ignorado por incompatibilidade-de-proporção, exiba as dimensões/proporção originais do arquivo e as dimensões proporcionais sugeridas impressas pelo CLI.

Erros Comuns e Sinais de Alerta

Pensamento / Erro	Por que Falha e o Que Fazer em Vez Disso
"Vou apenas executar node bin/cli.js sem --size ou --format"	O fallback não-TTY escolhe silenciosamente 800x800 e jpg. Sempre confirme pasta, tamanho/altura (800px ou LxH) e formato (jpg/webp/avif) com o usuário primeiro e passe --dir, --size e --format.
"O usuário quer 800×800 em uma foto 1:2 — vou passar fit: cover ou escrever um script de corte personalizado"	Viola a regra principal: nunca cortar ou esticar silenciosamente. Deixe o CLI rejeitar incompatibilidades e fornecer dimensões proporcionais.
"Vou commitar .imagerc.json ou PNGs de teste em input/"	.imagerc.json, input/* e output/* (exceto .gitkeep) são ignorados pelo git para proteger a privacidade do usuário. Mantenha-os não rastreados.
"Vou passar --input sem --output"	Sem --output ou --dir, a saída recai para <cwd>/output. Sempre passe --dir (fluxo padrão) ou ambos --input e --output.