@tricolors/photo-optimization

GitHub Action y bootstrapper npm para auditar, limpiar y optimizar imágenes de repositorios. La Action puede generar alt text con visión y placeholders LQIP sin subir imágenes a un proveedor salvo que el provider elegido lo requiera explícitamente.

Modos

• audit: solo analiza y genera report.json, report.md y el Step Summary.
• cleanup: elimina únicamente imágenes sin uso con confianza alta y puede abrir una PR.
• optimize: convierte PNG/JPEG a WebP cuando la salida validada supera los umbrales de ahorro; actualiza referencias estáticas y puede abrir una PR con la tabla de ahorros.
• alt-text: genera .photo-optimization/alt.json con OpenAI por defecto (OPENAI_API_KEY) y Anthropic como alternativa. GitHub Models quedó retirado; una configuración explícita github-models intenta fallback automático a OpenAI/Anthropic si existen sus claves. La inyección en Markdown/HTML requiere altTextInject: true.
• placeholders: genera .photo-optimization/placeholders.json usando Bun.Image.placeholder() sin modificar las imágenes fuente.

Los reportes incluyen referencias, incertidumbre dinámica, errores de metadata y el estado de cada oportunidad. Los manifests son idempotentes: una imagen sin cambios reutiliza su entrada de alt text. La trazabilidad completa contra el issue está en docs/issue-2-compliance.md.

Instalación

Después de publicar el paquete:

npx --yes @tricolors/photo-optimization@latest init

El instalador detecta la raíz Git, framework y aliases simples de tsconfig.json/jsconfig.json. Genera:

• .github/workflows/photo-optimization.yml
• .photo-optimization.yml
• .photo-optimization/ en .gitignore

El workflow generado tiene filtros paths para imágenes y usa fetch-depth: 0. Con changed-only: true, la auditoría sigue leyendo el contexto completo para resolver referencias, pero limita estimaciones y mutaciones de cleanup/optimize/alt-text/placeholders a las imágenes de todo el rango del push (before-sha..HEAD), incluso cuando root apunta a un subproyecto.

Opciones del instalador:

npx --yes @tricolors/photo-optimization@latest init --dry-run
npx --yes @tricolors/photo-optimization@latest update --dry-run
npx --yes @tricolors/photo-optimization@latest update

init no sobrescribe archivos existentes. update actualiza solo archivos que contienen el marcador del instalador. --force permite actualizar archivos gestionados aunque no se use update.

Uso manual

name: Photo optimization

on:
  push:
    paths:
      - '**/*.png'
      - '**/*.jpg'
      - '**/*.jpeg'
      - '**/*.webp'
      - '**/*.avif'
      - '**/*.gif'
      - '**/*.svg'
  workflow_dispatch:

permissions:
  contents: write
  pull-requests: write

jobs:
  images:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
        with:
          fetch-depth: 0
      - id: images
        uses: TRICOLORS-STUDDIO/[email protected]
        with:
          mode: cleanup
          changed-only: 'true'
          before-sha: ${{ github.event.before }}
        env:
          GH_TOKEN: ${{ github.token }}
          GITHUB_TOKEN: ${{ github.token }}

El paquete npm publicado sustituye el tag candidato por el SHA inmutable del commit de release. Los binarios compilados no se versionan en Git: la Action descarga el asset correspondiente a Linux x64, macOS x64/arm64 o Windows x64 y su checksum SHA-256 desde el Release indicado por binary-version. La matriz CI ejecuta smoke tests de la Action en los tres sistemas soportados.

Configuración

.photo-optimization.yml es opcional. El archivo .photo-optimization.example.yml contiene una configuración completa con filtros de fuentes, umbrales de optimización, provider de alt text y límites de placeholders.

Los paths de configuración, aliases, assetDirs y reportes deben permanecer dentro del root. Symlinks que salgan del root generan error. sourceExtensions controla qué archivos se interpretan como texto; extensiones binarias conocidas se excluyen siempre.

Optimización

- id: images
  uses: TRICOLORS-STUDDIO/[email protected]
  with:
    mode: optimize
    quality: '82'
    min-savings-percent: '5'
    min-savings-bytes: '4096'
    max-width: '1920'
    create-pr: 'true'

Solo se convierten PNG/JPEG. La salida WebP debe ser válida, menor que el original y superar ambos umbrales. Si falla la actualización de referencias o la escritura, se revierte la operación. WebP/AVIF/GIF/SVG/TIFF/BMP no se re-encodean por defecto; AVIF/HEIC no se prometen como encoder Linux nativo.

Alt text y placeholders

El payload de visión contiene bytes en base64, no paths del filesystem. OpenAI es el provider predeterminado y usa OPENAI_API_KEY; Anthropic es una alternativa. GitHub Models quedó retirado, pero una configuración antigua github-models intenta fallback automático a los providers disponibles:

altTextProvider: openai # openai | anthropic | github-models (retired compatibility)
altTextModel: gpt-4o-mini
altTextInputCostPerMillion: 0.15
altTextOutputCostPerMillion: 0.60
altTextInject: true

El workflow generado proporciona OPENAI_API_KEY desde secrets.OPENAI_API_KEY; configura ese secret para usar alt text. Anthropic requiere ANTHROPIC_API_KEY. Configuraciones antiguas con GitHub Models hacen fallback automático cuando alguna de esas claves existe; no se requiere models: read porque GitHub Models fue retirado. No se escriben claves en config, logs o manifests. El manifest sidecar registra nombre amigable, alt text, hash, provider, modelo, versión de prompt, tokens y coste estimado. Además genera un Markdown individual estable por imagen bajo .photo-optimization/images/. Los precios por millón de tokens son configurables; para gpt-4o-mini se usa el valor conocido como estimación. Los errores quedan registrados y no inventan texto.

- uses: TRICOLORS-STUDDIO/[email protected]
  with:
    mode: placeholders
    placeholder-max-bytes: '2048'

Los placeholders se guardan en placeholders.json; no se inyectan automáticamente en landings ni se modifican fuentes sin una opción explícita.

Cleanup y PRs

cleanup elimina solo candidatos de confianza alta, conserva imágenes con referencias dinámicas/aliases sin resolver y usa staging con rollback. El script de PR es re-ejecutable: añade el intento a la rama, no falla si no quedan cambios y comenta una PR existente cuando gh pr create no puede crear otra.

Requiere contents: write, pull-requests: write y GH_TOKEN. mode: audit nunca muta archivos. Los manifests de optimize/alt-text/placeholders contienen únicamente los paths que el script debe stagear.

Desarrollo

Requiere Bun 1.3.14 o superior:

bun install --frozen-lockfile
bun run typecheck
bun test
bun run jscpd
bun run build:linux
bun run check:binary

La validación de CI cubre Linux, macOS y Windows para typecheck/tests y smoke tests de la Action. release.yml compila los cuatro targets soportados (Linux x64, macOS x64/arm64 y Windows x64), publica cada binario y su checksum sin notas automáticas ni menciones a usuarios. Los binarios compilados están ignorados y no se versionan en Git.

Publicar npm

La workflow .github/workflows/npm-publish.yml usa npm Trusted Publishing/OIDC, id-token: write y provenance:

1. Configura el trusted publisher en npmjs.com para este repositorio y workflow.
2. Crea primero el Release y luego ejecuta manualmente Publish npm package indicando su tag.
3. El workflow valida que el tag coincide con package.json y sustituye ACTION_REF por el SHA inmutable antes de publicar.
4. Si npm no habilita Trusted Publishing para el paquete, detén el proceso y decide explícitamente una alternativa; no guardes tokens en el código.