--- version: 1.0.0 updated: 2026-03-12 tags: [workspace, gitea, sync, repos] --- # Command: sync-repos Sincroniza workspaces locales con repositorios en Gitea: detecta repos nuevos en Gitea que no existen localmente, clona repos faltantes, actualiza metadata en la BD local, y detecta inconsistencias (huérfanos). ## Para el usuario ### Cuándo usar este comando Usar cuando necesites sincronizar tu estado local con Gitea: - Después de clonar el parent repo en una máquina nueva - Cuando otro nodo creó un workspace en Gitea - Para verificar consistencia entre local y Gitea - Después de ejecutar `/workspace:create-repo` en otra máquina ### Prerequisitos - Issue 0011b completado (comando /create-repo) - Variables de entorno configuradas: `GITEA_URL` y `GITEA_TOKEN` - Feature flag `workspace_commands` habilitado ### Variables de entorno requeridas ```bash export GITEA_URL="https://gitea.example.com" export GITEA_TOKEN="tu-token-de-api" export DATAFORGE_REPOS="./workspaces" # opcional, default: ./workspaces ``` ### Ejemplo de uso ```bash # Sincronización completa (con confirmación interactiva) /workspace:sync-repos # Solo análisis (dry-run) /workspace:sync-repos --dry-run ``` ### Salida esperada ``` Analizando workspaces locales... Consultando repositorios en Gitea... Plan de sincronización: Repos a clonar (2) — existen en Gitea pero no localmente: + data-pipeline-v2 (https://gitea.example.com/Bl4cksmith/data-pipeline-v2.git) + ml-training-service (https://gitea.example.com/Bl4cksmith/ml-training-service.git) Repos a actualizar metadata (1): ~ my-etl-pipeline Repos locales no en Gitea — huérfanos (1): ? old-experiment Total: 2 a clonar, 1 a actualizar, 1 huérfanos detectados ¿Ejecutar sincronización? (s/n): s Clonando data-pipeline-v2... ✓ data-pipeline-v2 clonado Clonando ml-training-service... ✓ ml-training-service clonado ⚠ old-experiment no está en Gitea (mantener local) Sincronización completada. Clonados: 2 Actualizados: 1 Huérfanos: 1 Workspaces activos: 4 ``` ## Para Claude ### Precondiciones Verificar antes de ejecutar: - [ ] Feature flag `workspace_commands` habilitado en `feature_flags.json` - [ ] Variables de entorno `GITEA_URL` y `GITEA_TOKEN` configuradas - [ ] Issue 0011b completado ### Flujo de implementación #### Paso 0: Verificar feature flag Leer `feature_flags.json`: ```json { "features": { "workspace_commands": { "enabled": true } } } ``` Si `enabled: false`, informar al usuario y detenerse. #### Paso 1: Detectar modo de ejecución Determinar si el usuario pasó `--dry-run`: - Con `--dry-run`: ejecutar solo análisis, no hacer cambios - Sin `--dry-run`: mostrar plan y pedir confirmación antes de ejecutar #### Paso 2: Ejecutar análisis vía `app.SyncWorkspacesCommand` El flujo completo está implementado en `app/workspace_sync.go`: ```go // Modo dry-run (solo análisis): err := app.SyncWorkspacesCommand(config, true) // Modo ejecución completa: err := app.SyncWorkspacesCommand(config, false) ``` El comando hace automáticamente: 1. Obtener workspaces locales desde SQLite 2. Consultar repos en Gitea (organización o usuario) 3. Comparar con `core.CompareWorkspaces()` (función pura) 4. Mostrar plan con ToClone, ToUpdate, Orphans 5. Si no dry-run: clonar repos faltantes y actualizar metadata #### Paso 3: Confirmación interactiva (si no --dry-run) Después de mostrar el plan: ``` ¿Ejecutar sincronización? (s/n): ``` - Si `n`: cancelar sin cambios - Si `s`: ejecutar sincronización completa #### Paso 4: Mostrar resultado final Mostrar resumen con conteos de clonados, actualizados, huérfanos. ### Decisiones de diseño importantes 1. **Huérfanos NO se eliminan**: Si un repo local no está en Gitea, solo se reporta como huérfano. NO se elimina automáticamente (podría ser un repo en desarrollo que no está pusheado aún). 2. **Dry-run por defecto** en análisis: El plan siempre se muestra antes de ejecutar, y siempre requiere confirmación. 3. **Confirmación obligatoria**: El comando SIEMPRE muestra el plan y pide confirmación antes de clonar o actualizar. 4. **Clonación secuencial**: Los repos se clonan uno a uno (no en paralelo por simplicidad). ### Manejo de errores | Error | Causa | Solución | |-------|-------|----------| | "GITEA_URL y GITEA_TOKEN son requeridos" | Variables de entorno no configuradas | `export GITEA_URL=... GITEA_TOKEN=...` | | "error al obtener repositorios de Gitea" | Token inválido o Gitea inaccesible | Verificar token y conectividad | | "Error clonando " | URL incorrecta o permisos insuficientes | Verificar credenciales git y permisos | | "error al abrir base de datos" | BD no inicializada | Ejecutar `dataforge` para inicializar BD | ### Feature flag Este comando requiere que `workspace_commands` esté habilitado: ```json { "features": { "workspace_commands": { "enabled": true } } } ``` Si está deshabilitado, informar al usuario: ``` El comando /sync-repos requiere que el feature flag 'workspace_commands' esté habilitado. Editar feature_flags.json y cambiar "enabled": true para workspace_commands. ``` ## Troubleshooting ### Error: "GITEA_URL y GITEA_TOKEN son requeridos" ```bash export GITEA_URL="https://gitea.example.com" export GITEA_TOKEN="tu-token" # Luego ejecutar de nuevo /workspace:sync-repos ``` ### Error: "error al obtener repositorios de Gitea" Verificar: 1. Gitea accesible: `curl -H "Authorization: token $GITEA_TOKEN" $GITEA_URL/api/v1/user` 2. Token tiene permisos de lectura de repositorios ### Error: "Error clonando " Posibles causas: - Credenciales git no configuradas para HTTPS - Repo privado sin permisos de acceso - URL de clone incorrecta Solución: ```bash # Verificar credenciales git git config --global credential.helper store # Verificar acceso manual git clone ``` ### Los huérfanos no desaparecen Los huérfanos son repos locales que no están en Gitea. Opciones: 1. Si el repo fue eliminado de Gitea: ejecutar `dataforge workspace clean ` 2. Si el repo debe estar en Gitea: pushear el repo a Gitea primero ### La BD local está desactualizada Usar `RebuildDBCommand` para reconstruir desde cero: ```bash dataforge rebuild-db ```