oss-prep

Preparación para open source

Una pasada previa al lanzamiento para un repositorio que está a punto de hacerse público. Un script realiza las comprobaciones mecánicas; tú lees el proyecto, juzgas lo que el script no puede, reportas y luego completas solo lo que el usuario elija.

El orden importa porque un error no se puede deshacer: una vez que un repositorio es público, todo en su historial ha sido visto. Las filtraciones de credenciales y datos personales van primero; lo genérico va al final.

1. Escanear

Ejecuta el escáner incluido desde la raíz del repositorio (Node 20 o superior, sin dependencias, solo lectura):

node <skill-dir>/scripts/scan.mjs <repo-dir>

Imprime JSON: summary cuenta los hallazgos fallidos por nivel, y cada hallazgo tiene un id, un level (block, warn, info), un status (pass, fail, skip) y evidence. Agrega --no-history para un historial muy grande solo si el usuario acepta omitir esa parte, y di que se omitió. Si gitleaks está instalado, también ejecuta gitleaks git <repo-dir> --redact --no-banner y combina sus hallazgos; conoce muchos más formatos de tokens.

Las reglas de secretos del escáner son patrones, por lo que debes esperar falsos positivos (accesorios de prueba, ejemplos de documentación) y no asumir que lo detectó todo. Revisa cada acierto tú mismo antes de reportarlo. Una línea se puede marcar como intencional con un comentario oss-prep: allow.

2. Leer y juzgar

Lee references/checklist.md para saber qué significa cada verificación, cómo distinguir un problema real del ruido y las verificaciones que solo tú puedes hacer. En resumen, más allá de los hallazgos del script:

• Lo que revelan el historial y los archivos. Revisa cada acierto de secreto y cada archivo sensible en el historial (git show <commit>:<path>). Busca nombres reales, correos electrónicos, números de teléfono, direcciones, datos de clientes o financieros, nombres de host internos y capturas de pantalla con datos privados en documentos o accesorios.
• Coherencia de la licencia. El texto de LICENCIA, package.json, el frontmatter de SKILL.md, README y cualquier encabezado por archivo deben coincidir. Observa el código de terceros empaquetado, las fuentes o imágenes y si sus licencias permiten la redistribución.
• README para un desconocido. Alguien que llegue desde una búsqueda debe aprender qué es, verlo (una captura de pantalla o un enlace de demostración), instalarlo y ejecutarlo, y encontrar la licencia, sin contexto privado.
• Cosas que solo funcionaron para el autor. Rutas locales codificadas, valores de .env que el proyecto necesita pero no documenta, scripts que asumen la máquina del autor.

3. Reportar

Escribe el informe en el idioma del usuario, con esta forma:

# Preparación para open source: <repo>

**Veredicto:** <Listo / Listo después de los elementos bloqueantes / No listo>, una frase del porqué.

## Bloqueante (corregir antes de hacer público)
- ❌ <título>: <lo que se encontró, con archivo:línea o commit> → <la corrección>

## Debería corregirse
- ⚠️ ...

## Agradable de tener
- 💡 ...

## Ya en su lugar
- ✅ <una línea cada uno, agrupados>

## Necesita que tú en GitHub
<configuraciones que el usuario cambia por sí mismo, con el comando gh exacto o la ruta de configuración>

Pon el elemento más grave primero. Sé específico: "src/config.ts:12 tiene una clave de OpenAI, también en el commit a1b2c3d" en lugar de "secretos encontrados". Di lo que no revisaste (sin gh, historial omitido, archivos binarios).

Luego pregunta qué elementos completar. Ofrece el conjunto obvio como predeterminado ("todos los archivos faltantes") y enumera cada opción para que el usuario pueda elegir.

4. Completar lo que el usuario eligió

Usa las plantillas en assets/templates/ como punto de partida y adáptalas a este proyecto; lee references/fixing.md primero. En resumen:

• Escribe archivos, nunca publiques. Crea o edita archivos solo en el árbol de trabajo. No hagas commit, push, cambies la visibilidad o configuración del repositorio, ni crees releases a menos que el usuario lo solicite específicamente.
• Coincide con el proyecto. Usa sus comandos reales, versión de Node, gestor de paquetes, licencia y ruta de contacto; escribe en el idioma del README (ambos, si el README es bilingüe). Omite las secciones que no apliquen en lugar de enviar marcadores de posición.
• Nunca elijas una licencia por el usuario. Si no hay ninguna, explica las opciones comunes en una frase cada una (MIT, Apache-2.0, GPL-3.0, AGPL-3.0, licencia dual) y pregunta. Copia el texto de la licencia oficial exactamente; no lo parafrasees ni lo reescribas de memoria.
• Los secretos en el historial no se solucionan eliminando el archivo. La credencial debe revocarse y reemplazarse primero; esa es tarea del usuario en la consola del proveedor. Reescribir el historial (git filter-repo) o publicar un repositorio nuevo son su decisión; explica ambos y no hagas ninguno sin un 'sí' claro.
• Las configuraciones de GitHub pertenecen al usuario. Proporciona los comandos gh exactos o las rutas de configuración de la referencia; ejecútalos solo si el usuario lo pide.

Termina ejecutando el escáner nuevamente y mostrando qué hallazgos cambiaron, además de lo que todavía queda para el usuario.