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:

   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:

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

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:

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

# 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:

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

./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

./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

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