Añadidos arhcivos basicos de repos
This commit is contained in:
@@ -0,0 +1,234 @@
|
||||
---
|
||||
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
|
||||
```
|
||||
Reference in New Issue
Block a user