From 77eca4c52eaf71286b1a91e48753aee0291c37a1 Mon Sep 17 00:00:00 2001 From: Egutierrez Date: Tue, 21 Apr 2026 23:41:48 +0200 Subject: [PATCH] =?UTF-8?q?docs:=20add=20sync=5Fsetup.md=20=E2=80=94=20pro?= =?UTF-8?q?cedure=20to=20link=20a=20PC=20to=20registry.organic-machine.com?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Covers the client-side linking flow (not the server deploy, which already lives in bash/functions/infra/setup_registry_api.md): - Requisitos: server UP, fn binary, pass con 3 entradas, GPG desbloqueada. - Paso 1: ~/.fn_pc (identidad). - Paso 2: FN_REGISTRY_API + REGISTRY_API_TOKEN — 3 opciones (zshrc snippet desde pass, direnv por proyecto, a mano por sesión). - Paso 3-4: verificar con fn sync status + primer fn sync. - Troubleshooting table (401, 403, localhost:8420, GPG cache, etc). docs/README.md enlaza al nuevo fichero. registry.db actualizada tras primer sync contra el server desde esta sesión. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/README.md | 1 + docs/sync_setup.md | 166 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 167 insertions(+) create mode 100644 docs/sync_setup.md diff --git a/docs/README.md b/docs/README.md index 344bd58c..df6f7550 100644 --- a/docs/README.md +++ b/docs/README.md @@ -8,6 +8,7 @@ Registry personal de código con búsqueda FTS. Diseñado para composición func - `types.md` — Schema de la tabla types - `integrity.md` — Reglas de integridad y referencias cruzadas - `architecture.md` — Visión general del sistema +- `sync_setup.md` — Vincular una PC al server `registry.organic-machine.com` (env vars, `fn sync`, troubleshooting) ## Tablas diff --git a/docs/sync_setup.md b/docs/sync_setup.md new file mode 100644 index 00000000..d3a22fd3 --- /dev/null +++ b/docs/sync_setup.md @@ -0,0 +1,166 @@ +# 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 "" 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).