egutierrez
2a3d780347
Adds `fn doctor` read-only diagnostic command with subcommands artefacts, services, sync, uses-functions, unused, and --json flag for agents. Each subcommand wraps a registry function in functions/infra/. New functions: - artefact_doctor, services_status, pc_locations_drift, audit_uses_functions, find_unused_functions (Go diagnostics) - backup_sqlite_db, rotate_backups, wait_for_http, wait_for_port, port_kill, tail_journal, pre_commit_hook_install (bash utilities) - notify_telegram (Go HTTP) - backup_all pipeline (tag launcher) Plus prior session leftovers (scan_secrets_in_dirty, append_diary_entry, git utilities, http_session_cookie_middleware, compile/full-git pipelines). Fixes pc_locations_drift filepath.Join bug with absolute dir_path. Documents fn doctor in CLAUDE.md, .claude/rules/fn_doctor.md (rule 23), docs/architecture.md, CHANGELOG.md (2026-05-07), and diary entry. First fn doctor uses-functions run found drift in 7/12 apps (deuda para sincronizar app.md con imports reales). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
150 lines
5.1 KiB
Markdown
150 lines
5.1 KiB
Markdown
# Arquitectura del sistema
|
|
|
|
---
|
|
|
|
## Dos bases de datos, dos propósitos
|
|
|
|
| | Registry (esta BBDD) | Operacional (por proyecto) |
|
|
|---|---|---|
|
|
| **Qué almacena** | Lo que sabes hacer | Lo que has hecho y cómo fluye |
|
|
| **Naturaleza** | Conocimiento estático | Conocimiento dinámico |
|
|
| **Cuándo cambia** | Solo al añadir código | En cada proyecto activo |
|
|
| **Scope** | Compartida entre todos los proyectos | Local a cada proyecto |
|
|
| **Tablas** | `functions`, `types` | `entities`, `relations` |
|
|
|
|
---
|
|
|
|
## Registry — estructura de directorios
|
|
|
|
```
|
|
fn-registry/
|
|
functions/
|
|
core/
|
|
filter_slice.go
|
|
filter_slice.md
|
|
finance/
|
|
parse_ohlcv.go
|
|
parse_ohlcv.md
|
|
io/
|
|
fetch_ticks.go
|
|
fetch_ticks.md
|
|
pipelines/
|
|
tick_to_ohlcv.go
|
|
tick_to_ohlcv.md
|
|
components/
|
|
DataTable.tsx
|
|
DataTable.md
|
|
types/
|
|
core/
|
|
result.go
|
|
result.md
|
|
finance/
|
|
ohlcv.go
|
|
ohlcv.md
|
|
registry.db ← SQLite, solo índice FTS. Regenerable siempre.
|
|
fn ← binario CLI
|
|
```
|
|
|
|
Los archivos `.go` / `.tsx` son la **fuente de verdad del código**.
|
|
Los archivos `.md` son la **fuente de verdad de la documentación**.
|
|
`registry.db` es solo el índice — si se borra, `fn index` lo regenera en segundos.
|
|
|
|
---
|
|
|
|
## CLI — comandos
|
|
|
|
```bash
|
|
fn search "filter predicate sin mutar" # búsqueda FTS sobre nombre, descripción, tags, signature
|
|
fn search -k function -p pure "slice" # filtrar por kind y purity
|
|
fn search -l go -d finance "ohlcv" # filtrar por lang y domain
|
|
fn search -k component "tabla datos" # buscar componentes React
|
|
|
|
fn add # abre $EDITOR con template según kind
|
|
fn show filter_slice_go_core # imprime entrada completa
|
|
fn index # regenera registry.db desde los .md
|
|
|
|
fn list # lista todas las entradas
|
|
fn list -d finance # lista por dominio
|
|
fn list -k pipeline # lista solo pipelines
|
|
```
|
|
|
|
---
|
|
|
|
## Operacional — tablas por proyecto
|
|
|
|
Cada proyecto tiene su propia BBDD operacional que referencia IDs del registry.
|
|
|
|
### Entities
|
|
|
|
Instancias concretas de tipos registrados dentro de un contexto de ejecución.
|
|
|
|
| Campo | Tipo | Descripción |
|
|
|---|---|---|
|
|
| `id` | string | Identificador único |
|
|
| `name` | string | Nombre semántico (`ticks_btcusdt`) |
|
|
| `type_ref` | string | Referencia al `types.id` del registry |
|
|
| `description` | text | Qué representa en este dominio concreto |
|
|
| `tags` | []string | Etiquetas |
|
|
|
|
### Relations
|
|
|
|
Cómo las entidades se conectan a través de funciones o pipelines.
|
|
|
|
| Campo | Tipo | Descripción |
|
|
|---|---|---|
|
|
| `id` | string | Identificador único |
|
|
| `from_entity` | string | Entidad origen |
|
|
| `to_entity` | string | Entidad destino |
|
|
| `via` | string | `functions.id` que transforma |
|
|
| `description` | text | Qué ocurre en esta transformación |
|
|
| `purity` | enum | `pure` \| `impure` |
|
|
|
|
---
|
|
|
|
## El agente y el registry
|
|
|
|
El agente consulta el registry para:
|
|
|
|
1. **Descubrir** qué funciones y tipos existen en un dominio
|
|
2. **Razonar** sobre composabilidad comparando `returns` con `uses_types`
|
|
3. **Priorizar** funciones puras para el núcleo del pipeline
|
|
4. **Aislar** impuras en los bordes
|
|
5. **Verificar** que los contratos no están rotos comparando `version`
|
|
|
|
El agente consulta la operacional para:
|
|
|
|
1. Entender qué entidades fluyen en este proyecto concreto
|
|
2. Ver qué transformaciones ya están modeladas
|
|
3. Detectar patrones de uso frecuentes
|
|
|
|
---
|
|
|
|
## Capa diagnostica: `fn doctor`
|
|
|
|
Sobre el modelo registry+operations existe el comando `fn doctor` (read-only) que reporta estado del sistema:
|
|
|
|
- `artefacts` — salud por artefacto (git/venv/manifest/upstream).
|
|
- `services` — apps tag `service` + systemctl + puerto.
|
|
- `sync` — drift `pc_locations` BD vs disco del PC actual.
|
|
- `uses-functions` — drift entre imports reales en codigo de apps y `uses_functions` declarado en `app.md`.
|
|
- `unused` — funciones del registry sin consumidores.
|
|
|
|
Cada subcomando es wrapper fino sobre una funcion del registry (`functions/infra/{artefact_doctor,services_status,pc_locations_drift,audit_uses_functions,find_unused_functions}.go`). La logica vive en el registry; el CLI solo formatea. `--json` produce salida estructurada para agentes. Detalle en `.claude/rules/fn_doctor.md`.
|
|
|
|
Util tras deploys, `fn sync`, `git pull` masivos o como gate antes de evaluar metricas del bucle reactivo.
|
|
|
|
---
|
|
|
|
## Mejoras incorporadas al schema v1.0
|
|
|
|
| Problema | Solución |
|
|
|---|---|
|
|
| IDs frágiles con colisiones | Formato `{name}_{lang}_{domain}` + UUID interno |
|
|
| `lang` libre fragmenta el índice | Enum controlado, normalizado al indexar |
|
|
| Sin versionado | Campo `version` semver en functions y types |
|
|
| `file_path` absoluta se rompe al mover | Siempre relativa a la raíz del registry |
|
|
| Sin contexto de dominio | Campo `domain` obligatorio |
|
|
| Sin trazabilidad temporal | `created_at` / `updated_at` automáticos |
|
|
| `signature` ambigua en lenguajes dinámicos | Convención formal definida para Python/SQL |
|
|
| Pura que devuelve opcional mal modelada | Regla: modelar como tipo suma, no `returns_optional: true` |
|