repo_Claude/.claude/commands/workspace/sync-repos.md

version, updated, tags

version	updated	tags
1.0.0	2026-03-12	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

export GITEA_URL="https://gitea.example.com"
export GITEA_TOKEN="tu-token-de-api"
export DATAFORGE_REPOS="./workspaces"  # opcional, default: ./workspaces

Ejemplo de uso

# 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:

{
  "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:

// 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:

{
  "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"

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:

# 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:

dataforge rebuild-db