egutierrez
5bee3d813f
- 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) <noreply@anthropic.com>
59 lines
3.5 KiB
Markdown
59 lines
3.5 KiB
Markdown
## 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
|
|
|
|
```
|
|
<artefacto_padre>/
|
|
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/<lo_que_sea>/` (gitignored, sin contexto) |
|
|
| Prototipo ligado a un analysis/app/proyecto que reutiliza su entorno | `<padre>/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/<p>/apps/<a>/` |
|
|
|
|
`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
|
|
```
|