Mantenedor de Repositorios
Flujo de trabajo sistemático para transformar perfiles de GitHub fragmentados en repositorios profesionales, limpios y mantenibles.
Resumen
Ejecuta la limpieza en 6 fases. Omite las fases que no apliquen. Siempre obtén la confirmación del usuario en acciones destructivas (eliminación, renombrado, fusión).
Principios Fundamentales (No Negociables)
Cada repositorio — nuevo o antiguo, activo o archivado — debe tener estos cuatro documentos fundamentales. No consideres que una limpieza está completa hasta que los cuatro estén verificados.
| Documento | Regla | Por qué |
|---|---|---|
| LICENCIA | Cada repositorio público obtiene una LICENCIA. Por defecto MIT a menos que el usuario especifique lo contrario. | Sin licencia, el código es "todos los derechos reservados" por defecto. Nadie puede usarlo legalmente. |
| README.md | Debe existir con al menos: nombre del proyecto, descripción de una oración e instrucciones de uso/instalación si aplica. | Es lo primero que ve cada visitante. Un README vacío o faltante indica abandono. |
| .gitignore | Debe coincidir con el lenguaje principal (Python/PHP/Node/etc.). Nunca subir artefactos de compilación, caché, archivos env o configuraciones de IDE. | Evita la filtración accidental de secretos y mantiene los diffs legibles. |
| Descripción de GitHub | El campo description nunca debe estar vacío. Una oración, en español o inglés claro (o que coincida con el idioma del repositorio). | Aparece en resultados de búsqueda, pines de perfil y tarjetas sociales. |
Si a un repositorio le falta alguno de los cuatro, arreglarlo tiene prioridad sobre fusionar, renombrar o refactorizar.
Fase 1: Escanear y Diagnosticar
Obtén la lista completa de repositorios a través de la API de GitHub:
curl -sH "Authorization: Bearer TOKEN" \
"https://api.github.com/user/repos?per_page=100&affiliation=owner"
Verifica en cada repositorio:
LICENSE,.gitignore,README.mdfaltantes- Campo
descriptionvacío - Inconsistencias en nombres (mayúsculas/minúsculas mezcladas, nombres demasiado largos)
- Duplicados o series obvias (ej.,
project,project-v2,project-mineru) - Nombres que contengan
outdated,deprecated,old,test
Fase 2: Estandarizar Archivos Base
Para cada repositorio activo, asegura que exista el conjunto mínimo de archivos:
| Archivo | Regla |
|---|---|
LICENSE | Por defecto MIT a menos que el usuario especifique lo contrario |
.gitignore | Coincidir con el lenguaje principal (Python/PHP/Node) |
README.md | Debe existir; reescribir si solo es un marcador de posición |
| Descripción de GitHub | Resumen de una oración a través de la API |
Actualización masiva a través de la API de Contenidos de GitHub (PUT /repos/{owner}/{repo}/contents/{path}).
Crítico: Las here-strings de PowerShell corrompen los bloques de código de triple backtick en Markdown. Usa scripts de Python para la generación masiva de README para evitar fallos de escape de ` a ```.
Fase 3: Gestionar Repositorios Obsoletos
Árbol de decisión:
| Condición | Acción |
|---|---|
El nombre contiene outdated / deprecated / old | Archivar o eliminar |
| Reemplazado por un repositorio más nuevo | Archivar + enlace en README al sucesor |
| El historial de un repositorio público contiene secretos filtrados (claves API) | Eliminar (archivar deja el historial intacto) |
| Repositorio privado contiene claves, contraseñas, configuraciones privadas o datos personales | El usuario puede ignorar las reglas de filtración; tratar como estado privado aceptable a menos que pidan sanitizar |
| Útil como referencia pero sin mantenimiento | Archivar |
Los repositorios archivados son de solo lectura. Para modificar un repositorio archivado (renombrar, actualizar README), desarchiva primero (PATCH {"archived": false}), haz los cambios, luego vuelve a archivar.
Fase 4: Fusionar Repositorios Relacionados
Cuando 2+ repositorios son variantes del mismo sistema (diferentes backends, motores, adaptadores):
Opción A — Monorepo (Recomendado)
Crea un nuevo repositorio limpio (sin historial). Coloca cada variante en un subdirectorio engines/{nombre}/.
project-suite/
├── main.py # motor predeterminado
├── engines/
│ ├── babeldoc/
│ └── mineru/
└── README.md
Preserva el punto de entrada y la configuración de cada motor. Actualiza el README raíz para explicar cómo cambiar entre ellos.
Opción B — Submódulo de Git Mantén los repositorios independientes. Agrega submódulos en el repositorio padre. Úsalo cuando la preservación del historial sea más importante que la simplicidad.
Opción C — Mantener Independientes y Enlazar No fusiones. Agrega enlaces cruzados en los README. Úsalo cuando las variantes hayan divergido significativamente.
Si el historial contiene secretos: Siempre crea un nuevo repositorio limpio y copia la instantánea actual (a través de descarga zip + re-confirmación). No uses git merge ni git submodule, ya que las filtraciones del historial persistirán.
Fase 5: Renombrar Repositorios
API PATCH: PATCH /repos/{owner}/{repo} con {"name": "new-name"}.
Directrices:
- Todo en minúsculas, solo guiones
- Máximo 3-4 palabras
- Eliminar palabras redundantes (
basado-en,diseño-y-desarrollo) - Agregar el sufijo
outdateda los repositorios archivados si aún no está presente
GitHub redirige automáticamente las URL antiguas por un período, pero los marcadores y scripts pueden romperse. Confirma con el usuario antes de renombrar repositorios con estrellas o bifurcados.
Fase 6: Refactorización a Nivel de Código
Después de que la estructura remota esté limpia, refactoriza el código dentro de los repositorios:
- Terminología unificada — Reemplaza nombres de marca hardcodeados con términos genéricos (
GPTProcessor→LLMProcessor) mientras preservas los IDs de modelo de API reales (gpt-4,gpt-5). - Renombrado de archivos — La API de Contenidos de GitHub no tiene renombrado; crea un nuevo archivo con contenido actualizado, elimina el archivo antiguo.
- Reorganización de directorios — Usa patrones
engines/,variants/, ocore/+adapters/para proyectos con múltiples sabores.
Subir Grandes Refactorizaciones Locales al Remoto
Cuando el usuario descarga código localmente, hace cambios pesados (renombrados de archivos, renombrados de variables, reescrituras estructurales) y necesita subir de vuelta al repositorio remoto.
Escaneo de Secretos Pre-Push (OBLIGATORIO)
Antes de hacer push, primero se debe escanear en busca de fugas de secretos. Si se encuentra algo, reporta inmediatamente y no continúes con el push.
Excepción de repositorio privado: Si el repositorio de destino es confirmado como privado, se pueden ignorar las reglas de filtración de claves, contraseñas, configuraciones privadas, datos personales y otra información sensible. El escaneo puede servir como recordatorio, pero los aciertos no bloquean el push, no requieren eliminar y recrear el repositorio, ni reemplazar con variables de entorno, a menos que el usuario lo solicite explícitamente o planee hacerlo público.
Modo de escaneo (ambos deben ejecutarse — solo la expresión regular de tokens puede pasar por alto contraseñas en texto plano):
① Token de alta entropía / clave API:
grep -rn "sk-[A-Za-z0-9]\{20,\}\|ghp_[A-Za-z0-9]\{36\}\|ghu_\|github_pat_\|Bearer [A-Za-z0-9+/=]\{40,\}" \
--include="*.py" --include="*.js" --include="*.ts" --include="*.yaml" \
--include="*.env" --include="*.json" --include="*.bat" --include="*.sh" \
--exclude-dir=".git" .
② Contraseña en texto plano / helper de credenciales (las expresiones regulares de tokens no lo capturan; en la práctica se pasó por alto una línea echo "<contraseña sudo>" en askpass.sh, que se subió a GitHub con el commit inicial):
git ls-files -z | xargs -0 grep -nIE "password|passwd|contraseña|SUDO_ASKPASS|sshpass|^[[:space:]]*echo[[:space:]]+[\"'][^\"']{6,}[\"']" 2>/dev/null \
| grep -vE "\.md:|getenv|getpass|placeholder|example"
# y verifica manualmente archivos aislados como askpass.sh / *_secret* / .pgpass / .npmrc — el archivo completo es una credencial
Para repositorios públicos, cualquier acierto en cualquiera de los dos modos activa el proceso obligatorio a continuación. Para repositorios privados, solo se advierte al usuario, no es una condición de bloqueo. Ten en cuenta que se escanea git ls-files (conjunto rastreado); lo que está en .gitignore no cuenta como fuga, pero los archivos ya confirmados, incluso si ahora están en .gitignore, siguen en el historial.
Formato de informe:
[FUGA] scripts/eval.py:15 — sk-xxxx (fallback hardcodeado)
[FUGA] ui/ui_backend.py:33 — sk-xxxx (valor predeterminado hardcodeado)
Proceso obligatorio tras detectar una fuga:
- Informa inmediatamente al usuario qué archivo y qué línea
- Reemplaza con variables de entorno (
os.getenv("API_KEY")sin valor predeterminado) - Si ya se ha subido al remoto: informa al usuario y, tras obtener confirmación explícita, elimina y recrea el repositorio (el historial de git no se puede eliminar por completo con force push)
- El usuario revoca la clave del proveedor correspondiente
Lista de Verificación Pre-Push
Antes de hacer push, debes ejecutar:
git status
Confirma que no haya:
- Archivos sin seguimiento (untracked) — archivos nuevos no rastreados (omisiones comunes: docs/, scripts/, plantillas de configuración)
- Cambios no staged — modificaciones no agregadas
- Cambios a ser confirmados que incluyan archivos que no deberían subirse (claves, datos personales, scripts temporales)
Sin confirmación, no hagas push directamente.
Árbol de Decisión
| Situación | Acción Recomendada |
|---|---|
El repositorio local no tiene .git (zip descargado / archivos copiados) | Consulta el Escenario A a continuación |
El local es un git clone con historial, remoto sin cambios | git add → commit → push normal |
El local es un git clone, el remoto tiene nuevos commits | git pull --rebase o merge, resuelve conflictos, push |
El local es un git clone, los cambios son renombrados masivos + reescrituras | Consulta el Escenario B a continuación |
| Se quiere preservar el historial remoto pero reemplazar todo el código | Consulta el Escenario C a continuación |
Escenario A: El Local No Tiene Historial Git
Más común cuando el usuario descarga un zip, edita extensamente y luego quiere sincronizar de vuelta.
Opción A1 — Force Push (Proyectos Personales / Individuales)
# En la carpeta del proyecto local
git init
git add .
git commit -m "refactor: reescritura mayor"
git remote add origin https://github.com/OWNER/REPO.git
git branch -M main
git push -u origin main --force
⚠️ Destruye el historial remoto. Úsalo solo cuando el usuario confirme que el historial remoto es desechable.
Opción A2 — Preservar Historial Remoto (Recomendado para Repositorios Valiosos)
git clone https://github.com/OWNER/REPO.git temp-repo
cp -r temp-repo/.git ./tu-proyecto-local/
cd tu-proyecto-local
git add .
git commit -m "refactor: reescritura mayor"
git push
Esto mantiene todos los commits anteriores y agrega la refactorización como un solo commit nuevo.
Opción A3 — Nuevo Repositorio Limpio Si la reescritura es tan radical que es esencialmente un proyecto nuevo:
- Crea un nuevo repositorio en GitHub (debe incluir
descriptionen el cuerpo de creación o hacer PATCH inmediatamente después) - Sube el código local allí
- Archiva el repositorio antiguo con un enlace al sucesor en el README
Escenario B: Renombrados Masivos + Reescrituras en un Repositorio Clonado
Regla crítica: nunca mezcles renombrados de archivos y cambios de contenido en el mismo commit. Git lo tratará como "eliminar archivo antiguo + crear archivo nuevo" y perderá el vínculo del historial.
Estrategia de commits paso a paso:
# Paso 1: Solo renombrar
git mv modulo_antiguo.py modulo_nuevo.py
git mv utils_antiguas/ utils_nuevas/
git commit -m "refactor: renombrar módulos"
# Paso 2: Renombrar variables/clases
git add .
git commit -m "refactor: renombrar variables y clases"
# Paso 3: Cambios de lógica
git add .
git commit -m "feat: actualizar lógica principal"
Si el usuario ya mezcló todo en el árbol de trabajo:
# Guarda los cambios actuales, reproduce en etapas
git stash push -m "refactorización mezclada"
# Restaura solo los renombrados (usa git mv o mv manual + git add)
git mv archivo_antiguo archivo_nuevo
git commit -m "refactor: renombrar archivos"
# Restaura los cambios de contenido
git stash pop
# Resuelve conflictos si los hay, luego haz commit
Escenario C: Reemplazar Todo el Código pero Mantener el Historial
Útil cuando el usuario quiere empezar con código fresco pero mantener estrellas, issues y URL.
git checkout --orphan fresh-start
git rm -rf .
# Copia aquí el nuevo código local
git add .
git commit -m "init: reescritura limpia"
git branch -D main
git branch -m main
git push -u origin main --force
Verificar la Detección de Renombrados
Después de subir, verifica que Git haya rastreado correctamente los renombrados:
git log --follow -- archivo_nuevo.py
Si el historial está roto (muestra el archivo como completamente nuevo), el renombrado y el cambio de contenido se confirmaron juntos.
Seguridad y Cumplimiento
- Token de GitHub: Si se necesita un PAT, búscalo en la memoria del agente (no escribas aquí la ruta/cuenta/valor específicos). Nunca escribas el valor del token en ningún archivo que vaya a ser subido (incluyendo esta habilidad, README, configuraciones) — el contenido que contiene el token, una vez subido, es revocado por el escaneo de secretos de GitHub.
- Higiene del token: Después de operaciones masivas, instruye al usuario para que revoque el PAT inmediatamente en
https://github.com/settings/tokens. - Excepción de repositorio privado: Si un repositorio es privado, el agente puede ignorar las reglas de filtración de claves, contraseñas, configuraciones privadas, datos personales y otra información sensible. No bloquees el push, no fuerces la sanitización ni recomiendes la eliminación solo porque el historial privado contenga secretos, a menos que el usuario lo solicite o el repositorio pueda volverse público.
- Historial público con secretos: Si un repositorio público alguna vez confirmó claves de API, eliminar el repositorio es la única forma de purgar el historial de GitHub. Un force push con un historial sanitizado no garantiza la eliminación de los sistemas de copia de seguridad de GitHub.
- Repositorios públicos archivados con secretos: Si la eliminación no es aceptable, como mínimo elimina la visibilidad pública del repositorio (hazlo privado) o elimínalo y recréalo vacío con código limpio.
Referencia Técnica
Errores de Codificación (Windows)
PowerShell usa CP1252 por defecto para la salida estándar, lo que destruye los caracteres chinos y los bloques de código Markdown. Siempre reconfigura:
import sys
sys.stdout.reconfigure(encoding='utf-8')
Al usar Invoke-RestMethod en PowerShell con cuerpos JSON que contengan backticks o triple backticks, prefiere scripts de Python para la generación de contenido y evitar que la serialización JSON dañe ``` convirtiéndolo en `.
Patrones de la API de GitHub
Crear repositorio (nunca omitas description):
api_call("POST", "/user/repos", {
"name": "nombre-repo",
"private": True,
"description": "Resumen de una oración."
})
Crear/actualizar archivo:
import base64, json, urllib.request
payload = {
"message": "mensaje commit",
"content": base64.b64encode(content.encode('utf-8')).decode(),
"sha": sha_existente # requerido para actualizaciones
}
req = urllib.request.Request(
f"https://api.github.com/repos/{owner}/{repo}/contents/{path}",
method="PUT",
data=json.dumps(payload).encode(),
headers={"Authorization": f"Bearer {token}", ...}
)
Archivar/desarchivar:
api_call("PATCH", f"/repos/{owner}/{repo}", {"archived": True})
Renombrar repositorio:
api_call("PATCH", f"/repos/{owner}/{repo}", {"name": "nuevo-nombre"})
Eliminar repositorio:
api_call("DELETE", f"/repos/{owner}/{repo}")
Descarga Masiva Sin Clonar
Descarga una instantánea del repositorio como zip para evitar un git clone lento a través de redes inestables:
curl -sL "https://github.com/{owner}/{repo}/archive/refs/heads/main.zip" -o {repo}.zip
Recursos Incluidos
scripts/repo_analyzer.py— Escanea los repositorios de GitHub del usuario y genera recomendaciones de limpiezascripts/bulk_file_updater.py— Crea/actualiza de forma masiva LICENSE, .gitignore, README a través de la API de GitHub