From 1bef88da679579a80432b3fbbf43da0fcb1a94bf Mon Sep 17 00:00:00 2001 From: Egutierrez Date: Tue, 5 May 2026 23:54:34 +0200 Subject: [PATCH] =?UTF-8?q?docs(rules):=20a=C3=B1ade=20reglas=20de=20artef?= =?UTF-8?q?actos=20y=20playgrounds?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Nueva regla 20: artefactos.md (paraguas para apps/analysis/vaults/projects/playgrounds) - Nueva regla 21: playgrounds.md (prototipos rapidos dentro de un padre) - INDEX.md y CLAUDE.md actualizados con referencias Co-Authored-By: Claude Opus 4.7 (1M context) --- .claude/CLAUDE.md | 3 ++ .claude/rules/INDEX.md | 2 ++ .claude/rules/artefactos.md | 41 +++++++++++++++++++++++++ .claude/rules/playgrounds.md | 58 ++++++++++++++++++++++++++++++++++++ 4 files changed, 104 insertions(+) create mode 100644 .claude/rules/artefactos.md create mode 100644 .claude/rules/playgrounds.md diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index a2a05eb3..be44ffe7 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -10,6 +10,8 @@ Registry personal de codigo reutilizable con busqueda FTS. Diseñado para compos **Sub-repos:** cada app y cada analysis es su propio repo Gitea en `dataforge/` con branch `master` (ver ADR 0002). Los slash commands `/full-git-push` y `/full-git-pull` orquestan push/pull/clone de fn_registry + todos los sub-repos + `fn sync`. `/full-git-push` auto-inicializa apps/analyses sin `.git` via `ensure_repo_synced_bash_infra`. Los `vaults/` y `subrepos/` NO entran en este flujo. +**Artefactos:** termino paraguas para apps, analysis, vaults, projects y playgrounds — todo lo que NO es codigo reutilizable. Usa "artefacto" cuando una afirmacion aplica a varios tipos a la vez para no repetir la lista. Ver `.claude/rules/artefactos.md` y `.claude/rules/playgrounds.md`. + **Reglas y convenciones:** ver `.claude/rules/INDEX.md` --- @@ -106,6 +108,7 @@ fn-registry/ docs/ # Specs de diseño docs/templates/ # Plantillas de frontmatter temp/ # Workspace efimero — pruebas, APIs, prototipos (gitignored, no indexado) + /playground/ # Prototipo rapido dentro de un artefacto padre (analysis/app/proyecto). No se indexa ``` --- diff --git a/.claude/rules/INDEX.md b/.claude/rules/INDEX.md index 2a303f79..d87f7d95 100644 --- a/.claude/rules/INDEX.md +++ b/.claude/rules/INDEX.md @@ -23,3 +23,5 @@ Reglas operativas del proyecto. Cada archivo es una regla independiente. | 17 | [apps_tbd.md](apps_tbd.md) | Trunk-based development obligatorio en apps generadas con `fn` (registry exento) | | 18 | [uses_functions.md](uses_functions.md) | Convencion de uses_functions para C++: el .md del consumidor declara las dependencias | | 19 | [cpp_apps.md](cpp_apps.md) | Estandarizacion de apps C++: estructura, CMake, app.md, sub-repo, runtime — apunta a cpp/PATTERNS.md y cpp/DESIGN_SYSTEM.md como autoritativas | +| 20 | [artefactos.md](artefactos.md) | Termino paraguas para apps, analysis, vaults, projects y playgrounds (todo lo que no es codigo reutilizable) | +| 21 | [playgrounds.md](playgrounds.md) | Prototipos rapidos dentro de un artefacto padre — heredan entorno, no se indexan, no tienen repo propio | diff --git a/.claude/rules/artefactos.md b/.claude/rules/artefactos.md new file mode 100644 index 00000000..e9c2e7d5 --- /dev/null +++ b/.claude/rules/artefactos.md @@ -0,0 +1,41 @@ +## Artefactos: termino colectivo + +**"Artefacto"** es el termino paraguas para todo lo que vive en el registry pero NO es codigo reutilizable de `functions/` o `types/`. Sirve para no repetir "apps, analysis, vaults, projects, playgrounds" cada vez. + +Tipos de artefacto: + +| Tipo | Donde vive | Indexado en registry.db | Repo Gitea propio | +|---|---|---|---| +| **app** | `apps/`, `cpp/apps/`, `projects/

/apps//` | tabla `apps` | si (`dataforge/`) | +| **analysis** | `analysis//`, `projects/

/analysis//` | tabla `analysis` | si (`dataforge/`) | +| **vault** | `projects/

/vaults/` (symlink) | tabla `vaults` | no (datos fuera del repo) | +| **project** | `projects/

/` | tabla `projects` | no (vive dentro de fn_registry) | +| **playground** | `/playground/` | NO se indexa | no (vive dentro del padre) | + +Caracteristicas comunes de los artefactos: +- NO son codigo reutilizable. La reutilizacion vive en `functions/`. +- Tienen ciclo de vida propio (crear, modificar, archivar, borrar). +- `pc_locations` los unifica via `entity_type` (app, analysis, project, vault). +- Pueden importar funciones del registry; el registry NUNCA importa de un artefacto. + +### Cuando usar el termino + +Usa "artefacto" cuando hablas de varios tipos a la vez o cuando la afirmacion aplica a todos: + +- "Cada artefacto declara sus funciones del registry en su `.md`" (vale para apps y analyses). +- "Los artefactos no se importan desde `functions/`." +- "Esta regla aplica a cualquier artefacto desplegable" (apps + services). + +Cuando hables de UN tipo concreto, usa el nombre concreto: "esta app...", "este analysis...". No abuses del termino paraguas — es para evitar listas, no para difuminar. + +### Que NO es un artefacto + +- `functions/`, `python/functions/`, `bash/functions/`, `frontend/functions/` — codigo reutilizable. +- `types/`, `python/types/`, `frontend/types/` — tipos del registry. +- `sources/` — repos externos clonados para extraer funciones (gitignored). +- `temp/` — workspace efimero, ni siquiera versionado. +- `subrepos/` — espejos de repos externos para referencia. + +### Relacion con `pc_locations` + +Los artefactos con presencia en disco (app, analysis, project, vault) ya estan unificados en `pc_locations` via la columna `entity_type`. Los **playgrounds** NO entran en `pc_locations` porque son hijos de otro artefacto y se mueven con el (no tienen identidad propia entre PCs). diff --git a/.claude/rules/playgrounds.md b/.claude/rules/playgrounds.md new file mode 100644 index 00000000..3b6724d8 --- /dev/null +++ b/.claude/rules/playgrounds.md @@ -0,0 +1,58 @@ +## Playgrounds: prototipos rapidos dentro de un artefacto + +Un **playground** es un mini-artefacto efimero que vive **dentro** de otro artefacto (analysis, app o project) y reutiliza su entorno. Sirve para probar visualmente una idea (webapp, demo, dashboard, ejercicio interactivo) antes de decidir si se promueve a app independiente. + +Ejemplo canonico: `projects/osint_graph/analysis/gliner_glirel_tuning/playground/` — server FastAPI + index.html + JS vendored que reutiliza el `.venv` del analisis padre para visualizar las recetas del notebook 08 con UI interactiva. + +### Estructura + +``` +/ + playground/ # Un solo playground por padre (si necesitas mas, usa subdirs) + server.py | server.go | ... # Punto de entrada (single-file preferido) + index.html # UI si la hay + static/ # JS/CSS vendored (no node_modules ni pnpm) + server.log # Log local (gitignorable) +``` + +Si el playground crece a varios subdirs/modulos, ya no es playground — promover a app. + +### Reglas + +1. **Hereda el entorno del padre**. NO crea su propio `.venv`, `package.json`, ni dependencias. Si el padre es un analysis Python, usa `../.venv/bin/python3`. Si el padre es una app Go, comparte el `go.mod`. +2. **NO se indexa**. No tiene `app.md`, no aparece en `registry.db`, no tiene entrada en `pc_locations`. +3. **NO tiene repo propio**. Vive dentro del repo Gitea del artefacto padre y se mueve con el. +4. **Single-file preferido**. Un `server.py` o `main.go` con todo dentro. Si hace falta partir, considera promover a app. +5. **Vendor deps front**. JS/CSS como `.min.js` en `static/`, sin `node_modules`. Si necesitas pnpm/vite, ya no es playground. +6. **Reutiliza funciones del registry** igual que el padre — `sys.path` al `python/functions`, importar paquetes, etc. +7. **Ciclo de vida**: vive mientras la idea esta cruda. Una vez probada, dos caminos: + - **Promover a app** (extraer logica reutilizable como funciones del registry, crear `app.md`, mover a `apps/`). + - **Borrar** sin contemplaciones si el experimento no llevo a nada. + +### Cuando NO usar playground + +- Si necesitas correr en un VPS / tener systemd / health check → es un app + service, no playground. +- Si la idea ya esta clara y el codigo va a sobrevivir meses → arrancar como app desde el primer dia ahorra una migracion. +- Si necesitas operations.db, assertions, o el bucle reactivo → es app. +- Si el padre seria un proyecto entero solo para contener el playground → probablemente sea app standalone con `tags: [prototype]`. + +### Relacion con `temp/` + +| Cuando | Donde | +|---|---| +| Idea suelta sin contexto, prueba de API, snippet desechable | `temp//` (gitignored, sin contexto) | +| Prototipo ligado a un analysis/app/proyecto que reutiliza su entorno | `/playground/` (versionado con el padre) | +| Codigo que sobrevive y se reutiliza en otros sitios | extraer a `functions/` | +| Aplicacion ejecutable con identidad propia | `apps/` o `projects/

/apps//` | + +`temp/` es para cosas sin padre. Playground es para cosas con padre. Si dudas entre los dos, empieza en `temp/` y mueve a `playground/` cuando quede claro de que artefacto depende. + +### Lanzar un playground + +Sin convencion fija — depende del stack. El propio `server.py` o un README en el playground documenta como arrancarlo. Ejemplo del playground de OSINT: + +```bash +cd projects/osint_graph/analysis/gliner_glirel_tuning/playground +../.venv/bin/python3 server.py +# http://localhost:7878 +```