From f79f2e757cded657521f996e23b8332ac673398a 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 +++++++++++++++++++++++++++++++++++++++++++++ registry.db | Bin 17657856 -> 17657856 bytes 3 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). diff --git a/registry.db b/registry.db index 574aee1760ff6eec006ac7886db7337dcedd67f9..b8cb30170e2b86d27065822217f4dbff7a5103bd 100644 GIT binary patch delta 2324 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