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

- 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

- 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

- 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

- 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

- 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

- 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

- 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)

- 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)

- 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