fn_registry/docs/sync_setup.md

# Vincular una PC al registry_api

Procedimiento para conectar un clon de `fn_registry` al servidor centralizado `https://registry.organic-machine.com` y tener `fn sync` funcional.

> Esto es el flujo de **cliente**. Para desplegar el server en un VPS, ver `bash/functions/infra/setup_registry_api.md`.

---

## Qué hace `fn sync`

Sincroniza contra `registry_api` todo lo que **no** es regenerable por `fn index`:

- `proposals` — propuestas de cambio al registry
- `apps` · `projects` · `analysis` · `vaults` — metadata (no el código)
- `pc_locations` — mapa de dónde vive cada cosa en cada PC

Lo regenerable (`functions`, `types`, `unit_tests`) se reconstruye localmente con `fn index` a partir de los `.md` + fuentes.

---

## Requisitos

1. **El server está arriba** y tú tienes acceso:
   ```bash
   curl -sS -o /dev/null -w "%{http_code}\n" https://registry.organic-machine.com/api/status
   # Esperado: 401 (basicAuth gate — significa que el server responde)
   ```

2. **`fn` compilado:**
   ```bash
   CGO_ENABLED=1 go build -tags fts5 -o fn ./cmd/fn/
   ```

3. **`pass` con las 3 entradas de credenciales** (generadas al montar el server):
   ```
   pass registry/basicauth-user
   pass registry/basicauth-pass
   pass registry/api-token
   ```

4. **GPG desbloqueado** (para que `pass` pueda leer). Si no lo está, en el primer uso te lo pedirá una vez por sesión.

---

## Paso 1 — Identidad de esta PC

Cada PC se identifica con un nombre corto y único (aparece en `pc_locations` del server y en `fn sync status`).

```bash
echo "home-wsl" > ~/.fn_pc     # Ejemplos válidos: home-wsl, work-mac, laptop-linux
cat ~/.fn_pc                   # verifica
```

Reglas:
- Sin espacios ni caracteres raros — `[a-z0-9-]` idealmente.
- No repetir entre PCs — es el identificador en el server.

---

## Paso 2 — Variables de entorno

`fn sync` lee dos env vars:

- `FN_REGISTRY_API` — URL del server con basicAuth embebido (`https://user:pass@host`)
- `REGISTRY_API_TOKEN` — token Bearer que se envía en el header `Authorization`

### Opción A — snippet en `~/.zshrc` (o `~/.bashrc`)

Añade al final:

```bash
# fn_registry sync — credenciales desde pass (GPG)
if command -v pass >/dev/null 2>&1; then
  export FN_REGISTRY_API="https://$(pass registry/basicauth-user | head -n1):$(pass registry/basicauth-pass | head -n1)@registry.organic-machine.com"
  export REGISTRY_API_TOKEN="$(pass registry/api-token | head -n1)"
fi
```

Notas:
- Evalúa `pass` en cada arranque de shell — GPG puede pedir la pass una vez por sesión.
- Si no tienes `pass` (PC nueva sin el password store montado), el `if` evita errores.

### Opción B — `direnv` por proyecto

Si prefieres que solo se activen dentro de `fn_registry/`, crea `.envrc` (gitignored):

```bash
# fn_registry/.envrc
export FN_REGISTRY_API="https://$(pass registry/basicauth-user | head -n1):$(pass registry/basicauth-pass | head -n1)@registry.organic-machine.com"
export REGISTRY_API_TOKEN="$(pass registry/api-token | head -n1)"
```

Luego `direnv allow` dentro del directorio.

### Opción C — a mano por sesión

Para pruebas puntuales sin modificar ningún rc:

```bash
export FN_REGISTRY_API="https://$(pass registry/basicauth-user | head -n1):$(pass registry/basicauth-pass | head -n1)@registry.organic-machine.com"
export REGISTRY_API_TOKEN="$(pass registry/api-token | head -n1)"
```

---

## Paso 3 — Verificar

```bash
./fn sync status
```

Debe mostrar `API: https://registry.organic-machine.com` (no `http://localhost:8420`), la identidad de tu PC, y los conteos locales.

Si ves `API: http://localhost:8420`, las env vars no están exportadas en esta shell — revisa Paso 2.

---

## Paso 4 — Primer sync

```bash
./fn sync
```

Salida esperada:
```
syncing as "<pc-name>" against https://registry.organic-machine.com...
done. sent N items, server updated M, received K, imported L locally
```

Lo que pasa:
1. **Push**: tu PC envía `proposals`, `apps`, `projects`, `analysis`, `vaults` y las `pc_locations` de esta máquina.
2. **Pull**: el server te devuelve lo que otras PCs han subido.
3. **Import**: lo recibido se mete en tu `registry.db` local.

A partir de aquí, corre `fn sync` cuando quieras propagar cambios o recoger los de otra PC.

---

## Ver qué hay en cada PC

```bash
./fn sync locations
```

Muestra el mapa `(entity, pc_id, dir_path, status)` — útil para saber en qué máquina vive cada app/analysis/vault.

---

## Troubleshooting

| Síntoma | Causa probable | Fix |
|---------|----------------|-----|
| `cannot reach server: ... localhost:8420` | Env vars no exportadas | Paso 2 — revisa `env \| grep FN_REGISTRY` |
| `HTTP 401` desde curl o `fn sync` | basicAuth incorrecto | Regenerar `pass registry/basicauth-pass` y re-deploy del server con `setup_registry_api` |
| `HTTP 403` con basicAuth OK | `REGISTRY_API_TOKEN` expirado o vacío | Rotar token en el server y actualizar `pass registry/api-token` |
| `context deadline exceeded` apuntando a la URL correcta | Server caído o DNS roto | `curl https://registry.organic-machine.com/api/status` — si no responde, revisar el VPS |
| `fn sync status` muestra otro `pc_id` | `~/.fn_pc` mal escrito | Editar el fichero; un valor por línea, sin comillas |
| GPG pide pass cada comando | Agente GPG no persistiendo | `echo "default-cache-ttl 28800" >> ~/.gnupg/gpg-agent.conf && gpg-connect-agent reloadagent /bye` |

---

## Ver también

- `.claude/CLAUDE.md` — sección **Sync entre PCs** con los comandos detallados.
- `bash/functions/infra/setup_registry_api.md` — desplegar el server en un VPS nuevo.
- `apps/registry_api/` — código del servidor (Go + SQLite + Traefik basicAuth).