---
version: 1.0.0
updated: 2026-03-12
tags: [workspace, gitea, repo, creation]
---

# Command: create-repo

Crea un nuevo subrepo (child repository) en `workspaces/`, inicializándolo con la estructura core/shell/app, creando el repo en Gitea, y registrándolo en la base de datos local.

## Para el usuario

### Cuándo usar este comando

Usar cuando necesites crear un nuevo workspace (subrepo) dentro de Dataforge. El comando:

1. Solicita el nombre y descripción del repositorio
2. Muestra un resumen de lo que se creará
3. Pide confirmación antes de proceder
4. Crea el workspace completo (local + Gitea + BD)

### Prerequisitos

- Issues 0006, 0007, 0008 completados (workspaces base)
- Issue 0011a completado (comandos organizados)
- Gitea configurado y accesible (`GITEA_URL` y `GITEA_TOKEN` en env)
- Base de datos SQLite disponible

### 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
/workspace:create-repo
```

```
Nombre del repositorio: my-etl-pipeline
Descripción: ETL pipeline para datos de ventas
Tipo (go/data/etl/api) [go]: etl
¿Repositorio privado? (s/n) [n]: n

Resumen:
  Nombre:     my-etl-pipeline
  Path local: ./workspaces/my-etl-pipeline
  Gitea:      https://gitea.example.com/Bl4cksmith/my-etl-pipeline
  Módulo Go:  gitea.../my-etl-pipeline
  Tipo:       etl
  Privado:    no

¿Crear repositorio? (s/n): s

✓ Directorio creado: ./workspaces/my-etl-pipeline
✓ Templates generados (core/, shell/, app/, go.mod, main.go)
✓ Git inicializado
✓ Repositorio Gitea creado
✓ Push inicial completado
✓ Registrado en base de datos

Workspace creado: ./workspaces/my-etl-pipeline

Para trabajar en él:
  cd workspaces/my-etl-pipeline
```

## 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
- [ ] Directorio `workspaces/` existe (o se puede crear)

### Flujo de implementación

#### Paso 1: Solicitar inputs interactivos

Preguntar al usuario:

1. **Nombre del repositorio** — debe ser URL-safe (lowercase, alfanumérico, guiones)
   - Validar con `core.ValidateRepoName()`
   - Ejemplos válidos: `my-api`, `etl-pipeline`, `data-processor`
   - Ejemplos inválidos: `My API`, `my_api`, `-test-`

2. **Descripción** — texto libre, puede estar vacío

3. **Tipo** — uno de: `go` (default), `data`, `etl`, `api`

4. **¿Privado?** — `s/n`, default `n`

#### Paso 2: Mostrar resumen y pedir confirmación

```
Resumen:
  Nombre:     <nombre>
  Path local: <DATAFORGE_REPOS>/<nombre>
  Gitea:      <GITEA_URL>/Bl4cksmith/<nombre>
  Módulo Go:  gitea-dgg044oo04woo4ggcsws4gk0.organic-machine.com/Bl4cksmith/dataforge/<nombre>
  Tipo:       <tipo>
  Privado:    <sí/no>

¿Crear repositorio? (s/n):
```

Si el usuario responde `n`, cancelar sin hacer cambios.

#### Paso 3: Ejecutar creación vía `app.CreateWorkspaceCommand`

El flujo completo está implementado en `app/workspace_create.go`:

```go
params := app.CreateWorkspaceParams{
    Name:        nombre,
    Description: descripcion,
    Type:        tipo,
    IsPrivate:   privado,
}
result, err := app.CreateWorkspaceCommand(config, params)
```

El comando hace automáticamente:
1. Validar nombre
2. Verificar que no existe en local ni en Gitea
3. Crear estructura `core/shell/app/`
4. Escribir templates (`go.mod`, `main.go`, `core/core.go`, `shell/shell.go`, `app/app.go`, `.gitignore`, `README.md`)
5. `git init` + configurar usuario
6. Crear repo en Gitea
7. Configurar remote y push inicial
8. Registrar en SQLite

**Rollback automático:** Si falla cualquier paso, limpia directorio local y elimina repo Gitea si se creó.

#### Paso 4: Mostrar resultado

```
✓ Workspace creado exitosamente

  Path local: <localPath>
  Gitea:      <giteaURL>
  Módulo Go:  <moduleName>

Para trabajar en él:
  cd <localPath>
```

### Manejo de errores

| Error | Causa | Solución |
|-------|-------|----------|
| "nombre de repositorio inválido" | Nombre no cumple reglas Gitea | Usar solo lowercase, alfanumérico y guiones |
| "ya existe un directorio" | Workspace ya creado localmente | Verificar `ls workspaces/` |
| "ya existe el repositorio en Gitea" | Repo creado en Gitea anteriormente | Verificar en Gitea o usar nombre diferente |
| "error al crear repositorio en Gitea" | Token inválido o sin permisos | Verificar `GITEA_TOKEN` |
| "error al hacer push inicial" | Credenciales git no configuradas | Configurar git credentials |

### Feature flag

Este comando requiere que `workspace_commands` esté habilitado:

```json
{
  "features": {
    "workspace_commands": {
      "enabled": true
    }
  }
}
```

Si está deshabilitado, informar al usuario que debe habilitarlo en `feature_flags.json`.

## Troubleshooting

### Error: "nombre de repositorio inválido"

El nombre debe cumplir las reglas de Gitea:
- Solo letras, números y guiones
- No puede empezar o terminar con guión
- Entre 2 y 100 caracteres

```bash
# Válidos:
my-api
etl-pipeline-v2
data-processor

# Inválidos:
My API        # espacios, mayúsculas
my_api        # guión bajo
-test-        # empieza/termina con guión
```

### Error: "GITEA_URL o GITEA_TOKEN no configurados"

```bash
export GITEA_URL="https://gitea.example.com"
export GITEA_TOKEN="tu-token"
# Luego ejecutar de nuevo
/workspace:create-repo
```

### Error: "ya existe un directorio en ./workspaces/<nombre>"

El workspace ya existe localmente. Opciones:
1. Usar nombre diferente
2. Eliminar directorio si fue creación fallida: `rm -rf workspaces/<nombre>`

### Error: "rollback falló"

En caso de rollback parcial, verificar manualmente:
```bash
# Ver estado local
ls workspaces/

# Ver repos en Gitea (vía API o interfaz web)
curl -H "Authorization: token $GITEA_TOKEN" $GITEA_URL/api/v1/user/repos
```