235 lines
6.2 KiB
Markdown
235 lines
6.2 KiB
Markdown
---
|
|
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 <repo>" | 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 <repo>"
|
|
|
|
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 <clone_url>
|
|
```
|
|
|
|
### 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 <slug>`
|
|
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
|
|
```
|