STP/README.md

# STP — Sistema de Transferencia Personal

Automatiza la configuración completa de una máquina Ubuntu LTS nueva: paquetes, PPAs, dotfiles, claves SSH, audio, drivers de video, servicios systemd y configuraciones de aplicaciones.

> Los archivos (documentos, fotos, etc.) los maneja Nextcloud por separado. El STP se ocupa del *entorno* del usuario.

---

## Primeros pasos en una máquina nueva

**Opción A — ejecución directa:**

```bash
bash <(curl -fsSL https://gitea.mateosaldain.uy/mateo/stp/raw/branch/main/bootstrap.sh)
```

**Opción B — manual:**

```bash
curl -fsSLo bootstrap.sh https://gitea.mateosaldain.uy/mateo/stp/raw/branch/main/bootstrap.sh
bash bootstrap.sh
```

El `bootstrap.sh` instala `git`, `curl` y otras dependencias base si no están disponibles, clona el repo en `~/.stp` (configurable con `stpDir`), y lanza `stp.sh`.

Durante la ejecución se pedirá la contraseña de las claves SSH cifradas por consola (módulo `ssh`) y permisos de administrador para restaurar impresoras (módulo `cups`).

**Después de que termine**, reiniciá el gestor de audio para que los auriculares Bluetooth queden como dispositivo por defecto:

```bash
systemctl --user restart wireplumber
```

---

## Comandos principales

```bash
# Ejecutar todos los módulos en orden
bash stp.sh

# Ejecutar un solo módulo
bash stp.sh --module registry

# Saltear módulos específicos
bash stp.sh --skip ssh

# Ver módulos disponibles (en orden de ejecución)
bash stp.sh --list

# Salida detallada (muestra también los ítems ya instalados)
bash stp.sh --verbose
```

El STP es **idempotente**: verifica el estado antes de actuar. Ejecutarlo varias veces es seguro.

---

## Orden de ejecución de módulos

El orden está definido en `config/modules` (un módulo por línea, `#` para comentarios).

| Módulo | Qué hace |
|---|---|
| `bootstrap` | Instala `yq` y `age` (requeridos por los demás módulos) |
| `ssh` | Descifra e instala claves SSH en `~/.ssh` |
| `registry` | Aplica todo lo declarado en `config/registry.yaml` |
| `thunderbird` | Instala Thunderbird (snap) y restaura el perfil |
| `claudeCode` | Configura el repositorio apt de Anthropic e instala `claude-code` |
| `easyEffects` | Restaura configuración y presets de EasyEffects |
| `wireplumber` | Restaura el estado de audio: dispositivo Bluetooth por defecto, perfiles, volúmenes por app |
| `cups` | Restaura las impresoras configuradas y sus drivers PPD |

---

## Configuraciones actualmente guardadas

### Paquetes (via registro)

| ID | Tipo | Paquete |
|---|---|---|
| curl, wget, git, vim, htop, tree, unzip | apt | igual al ID |
| buildEssential | apt | build-essential |
| virtualbox | apt | virtualbox |
| dbeaverCe | snap | dbeaver-ce |
| vscodium | flatpak | com.vscodium.codium |
| filezilla | flatpak | org.filezillaproject.Filezilla |
| angryIpScanner | flatpak | org.angryip.ipscan |
| anydesk | flatpak | com.anydesk.Anydesk |
| bitwarden | flatpak | com.bitwarden.desktop |
| bottles | flatpak | com.usebottles.bottles |
| bruno | flatpak | com.usebruno.Bruno |
| nextcloudDesktop | flatpak | com.nextcloud.desktopclient.nextcloud |
| easyEffects | flatpak | com.github.wwmm.easyeffects |
| flatseal | flatpak | com.github.tchx84.Flatseal |
| warehouse | flatpak | io.github.flattool.Warehouse |
| freecad | flatpak | org.freecad.FreeCAD |
| hidamari | flatpak | io.github.jeffshee.Hidamari |
| inkscape | flatpak | org.inkscape.Inkscape |
| libreoffice | flatpak | org.libreoffice.LibreOffice |
| logseq | flatpak | com.logseq.Logseq |
| obsStudio | flatpak | com.obsproject.Studio |
| openshot | flatpak | org.openshot.OpenShot |

### Configuraciones de aplicaciones (via módulos)

| Módulo | Archivo | Qué se restaura |
|---|---|---|
| `ssh` | `secrets/sshKeys.tar.gz.age` | Claves SSH con permisos correctos |
| `thunderbird` | `secrets/thunderbirdProfile.zip` | Cuentas, filtros y extensiones (excluye emails) |
| `claudeCode` | `config/keys/claude-code.asc` | Repositorio apt de Anthropic + paquete claude-code |
| `easyEffects` | `secrets/easyEffectsConfig.zip` | Configuración y presets de salida (HB-Flat, HB-Lite, HB-Mid, Heavy Bass) |
| `wireplumber` | `secrets/wireplumberState.zip` | Auriculares Bluetooth como salida por defecto, perfil A2DP, volúmenes por app |
| `cups` | `secrets/cupsConfig.zip` | 5 impresoras: Epson L8050 WiFi, Canon MP230, Samsung M2020, POS80, Cups PDF |

---

## Actualizar una configuración guardada

Volvé a ejecutar el script de captura correspondiente y commiteá el archivo generado:

```bash
bash scripts/encryptSsh.sh           && git add secrets/sshKeys.tar.gz.age
bash scripts/thunderbird/capture.sh  && git add secrets/thunderbirdProfile.zip
bash scripts/easyEffects/capture.sh  && git add secrets/easyEffectsConfig.zip
bash scripts/wireplumber/capture.sh  && git add secrets/wireplumberState.zip
bash scripts/cups/capture.sh         && git add secrets/cupsConfig.zip
```

---

## Agregar un paquete nuevo

Basta con agregar una entrada a `config/registry.yaml`. La próxima vez que corra el STP, detectará la nueva entrada y la aplicará.

```bash
# Desde Claude Code — agrega la entrada correctamente formateada
/addEntry neovim apt
/addEntry gimp flatpak appId=org.gimp.GIMP
/addEntry bashrc dotfile
```

O editá directamente `config/registry.yaml`:

```yaml
registry:
  - id: neovim
    type: apt

  - id: vscode
    type: snap
    package: code
    classic: true

  - id: gimp
    type: flatpak
    appId: org.gimp.GIMP

  - id: bash
    type: dotfile

  - id: networkManager
    type: service
    scope: system
    state: enable
```

### Tipos disponibles en el registro

| Tipo | Qué hace |
|---|---|
| `ppa` | Agrega un repositorio PPA a apt |
| `apt` | Instala un paquete con apt (soporta `minVersion` / `maxVersion`) |
| `snap` | Instala un paquete snap |
| `flatpak` | Instala una aplicación Flatpak |
| `dotfile` | Enlaza todos los archivos de `dotfiles/<id>/` a sus rutas en `$HOME/` |
| `service` | Habilita, deshabilita o mask un servicio systemd |
| `pipewire` | Instala y configura PipeWire como sistema de audio |
| `video` | Detecta la GPU y instala los drivers correspondientes |
| `docker` | Despliega archivos de configuración Docker desde `docker/<id>/` |

---

## Agregar una nueva configuración de aplicación

Para guardar y restaurar la configuración de una app nueva:

1. Crear `scripts/<appName>/capture.sh` — lee desde el directorio de datos de la app y genera un ZIP en `secrets/`
2. Crear `modules/<appName>.sh` — verifica si la app está instalada y si ya hay config; si no, restaura desde el ZIP
3. Agregar `<appName>` en `config/modules` después de `registry`
4. Ejecutar `bash scripts/<appName>/capture.sh` en la máquina actual
5. Commitear el archivo generado en `secrets/`

La restauración es automática en el próximo `stp.sh`. Si la config ya existe en la máquina destino, el módulo la saltea.

```bash
# Desde Claude Code — genera la estructura completa
/new-module nombreApp
```

---

## Dotfiles

Cada aplicación tiene su propia carpeta dentro de `dotfiles/`. Dentro de esa carpeta, los archivos respetan la misma ruta que tendrían en `$HOME/`:

```
dotfiles/
├── bash/
│   └── .bashrc
├── git/
│   ├── .gitconfig
│   └── .gitignore_global
└── neovim/
    └── .config/
        └── nvim/
            └── init.lua
```

Para activar una carpeta, basta con agregar una entrada en el registro:

```yaml
- id: bash
  type: dotfile

- id: neovim
  type: dotfile
```

El STP recorre todos los archivos de `dotfiles/bash/` y crea un enlace simbólico por cada uno en su ruta equivalente dentro de `$HOME/`. Si un archivo ya existe, guarda una copia con extensión `.stpbackup` antes de reemplazarlo.

---

## Claves SSH

Las claves se almacenan cifradas en el repo como `secrets/sshKeys.tar.gz.age`. El archivo está cifrado con `age` usando una contraseña y **es seguro hacer commit de él**.

**Cifrar las claves actuales** (correr en la máquina con las claves):

```bash
bash scripts/encryptSsh.sh
# → genera secrets/sshKeys.tar.gz.age
git add secrets/sshKeys.tar.gz.age && git commit -m "update ssh keys"
```

**Verificar el cifrado antes de hacer commit:**

```bash
age --decrypt secrets/sshKeys.tar.gz.age | tar -tzv
```

Durante la ejecución del STP, el módulo `ssh` pide la contraseña, descifra el archivo e instala las claves en `~/.ssh` con los permisos correctos. Las claves que ya existen se saltean sin sobrescribir.

---

## Variables de entorno

| Variable | Predeterminado | Efecto |
|---|---|---|
| `stpDir` | `~/.stp` | Directorio de clonado (bootstrap) |
| `stpLogFile` | `/tmp/stp-<timestamp>.log` | Ruta del log completo |