STP/.claude/commands/addEntry.md

# Agregar entrada al registro STP

Agregá una nueva entrada al registro STP para: $ARGUMENTS

---

## Procedimiento

1. Leé `config/registry.yaml` para verificar que no exista ya una entrada con el mismo `id`.
2. Identificá el tipo correcto según la descripción (ver sección **Tipos** más abajo).
3. Insertá la nueva entrada en `config/registry.yaml`, dentro de la lista `registry:`, respetando el orden:
   - Los `ppa` deben aparecer **antes** de cualquier `apt` que los requiera.
   - Dentro de cada grupo, el orden es cosmético; seguí el orden existente.
4. Confirmá el resultado mostrando la entrada agregada.

**Archivo a editar:** `config/registry.yaml`

---

## Tipos

### `apt` — paquete del gestor de paquetes

```yaml
- id: nombrePaquete
  type: apt
  # package: nombre-real   # solo si el nombre real difiere del id
  # minVersion: "1.2.3"    # versión mínima aceptable (opcional)
  # maxVersion: "1.2.3"    # versión máxima aceptable (opcional)
```

Campos:
- `id` — requerido, camelCase
- `package` — opcional; omitir si el id coincide con el nombre real del paquete apt
- `minVersion` — opcional; versión mínima aceptable (cadena de versión Debian, ej. `"2.38.1"`)
- `maxVersion` — opcional; versión máxima a instalar

**Comportamiento de instalación según los campos presentes:**

| `minVersion` | `maxVersion` | Qué instala |
|---|---|---|
| — | — | última versión disponible |
| `1.0` | — | última disponible (best-effort ≥ 1.0) |
| — | `2.0` | `package=2.0` |
| `1.0` | `2.0` | `package=2.0` (techo del rango aceptable) |
| `1.5` | `1.5` | `package=1.5` (versión exacta) |

Cuando `maxVersion` está presente, el módulo siempre instala esa versión exacta con `--allow-downgrades`, lo que garantiza que la máquina no quede con una versión superior al límite aunque ya tuviera el paquete instalado. Si la versión instalada ya satisface el rango `[minVersion, maxVersion]`, el paso se omite sin reinstalar.

### `ppa` — repositorio PPA de Ubuntu

```yaml
- id: nombrePpa
  type: ppa
  address: ppa:usuario/repositorio
```

Campos:
- `id` — requerido, camelCase
- `address` — requerido, formato `ppa:usuario/repositorio`

> Debe aparecer en el archivo **antes** del `apt` que instala paquetes de ese PPA.

### `snap` — aplicación snap

```yaml
- id: nombreApp
  type: snap
  # package: nombre-snap   # solo si el nombre real difiere del id
  # classic: true          # solo si el snap requiere confinamiento clásico
```

Campos:
- `id` — requerido, camelCase
- `package` — opcional
- `classic` — opcional; omitir si es `false`

### `flatpak` — aplicación Flatpak

```yaml
- id: nombreApp
  type: flatpak
  appId: com.ejemplo.App
  # remote: flathub        # opcional; flathub por defecto
```

Campos:
- `id` — requerido, camelCase
- `appId` — requerido, ID completo de la aplicación (ej. `org.gimp.GIMP`)
- `remote` — opcional; omitir si es flathub

### `dotfile` — configuración enlazada a `$HOME`

```yaml
- id: nombreApp
  type: dotfile
```

Campos:
- `id` — requerido, camelCase; debe coincidir con una carpeta dentro de `dotfiles/`

Los archivos en `dotfiles/nombreApp/` se enlazan simbólicamente a su ruta equivalente en `$HOME`.  
Ejemplo: `dotfiles/bash/.bashrc` → `~/.bashrc`

Si la carpeta `dotfiles/nombreApp/` no existe, crearla y colocar los archivos adentro antes de agregar la entrada.

### `service` — servicio systemd

```yaml
- id: nombreServicio
  type: service
  # name: nombre-servicio  # solo si el nombre real difiere del id
  scope: system            # system | user
  state: enable            # enable | disable | mask
```

Campos:
- `id` — requerido, camelCase
- `name` — opcional
- `scope` — requerido: `system` o `user`
- `state` — requerido: `enable`, `disable` o `mask`

### `pipewire` — configuración completa de PipeWire

```yaml
- id: pipewire
  type: pipewire
  replacePulseaudio: true
  packages:
    - pipewire
    - pipewire-audio
    - pipewire-pulse
    - wireplumber
    - libspa-0.2-bluetooth
  userServices:
    - pipewire
    - pipewire-pulse
    - wireplumber
```

Campos:
- `replacePulseaudio` — `true` para deshabilitar y enmascarar PulseAudio
- `packages` — lista de paquetes apt a instalar
- `userServices` — lista de servicios systemd de usuario a habilitar

### `video` — drivers de GPU (detección automática con `lspci`)

```yaml
- id: gpuDrivers
  type: video
  drivers:
    nvidia:
      packages:
        - nvidia-driver-535
        - nvidia-settings
    amd:
      packages:
        - mesa-vulkan-drivers
        - radeontop
        - vainfo
    intel:
      packages:
        - intel-media-va-driver
        - vainfo
```

Solo se instalan los paquetes del vendor detectado. Podés incluir uno, dos o los tres vendors.

---

### `docker` — configuración Docker (Compose o Dockerfile)

```yaml
- id: nombreServicio
  type: docker
  # destination: ~/docker/nombreServicio  # destino en el sistema (opcional, ese es el valor por defecto)
  # autostart: true                        # ejecutar docker compose up -d tras el deploy (opcional, false por defecto)
```

Campos:
- `id` — requerido, camelCase
- `destination` — opcional; directorio de destino donde se enlazan los archivos. Soporta `~`. Por defecto: `~/docker/<id>`
- `autostart` — opcional; si `true`, ejecuta `docker compose up -d` después de enlazar los archivos. Requiere un archivo compose en el destino

Los archivos del servicio deben estar en `docker/<id>/` dentro del repo. Se enlazan simbólicamente a `destination/`, respetando la estructura de subdirectorios.

Ejemplo de estructura:
```
docker/
  miServicio/
    compose.yaml
    .env.example
    config/
      nginx.conf
```

Si Docker no está instalado en la máquina, el paso se saltea con un aviso sin interrumpir el resto del STP.

---

## Convenciones

- `id` siempre en **camelCase**, sin guiones ni guiones bajos
- Omitir campos opcionales cuando no aplican — no usar `null` ni strings vacíos
- El campo `name`, `package` o `appId` solo es necesario cuando difiere del `id`