docs(rules): añade reglas de artefactos y playgrounds
- 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>
This commit is contained in:
@@ -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 |
|
||||
|
||||
@@ -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/<p>/apps/<a>/` | tabla `apps` | si (`dataforge/<a>`) |
|
||||
| **analysis** | `analysis/<t>/`, `projects/<p>/analysis/<t>/` | tabla `analysis` | si (`dataforge/<t>`) |
|
||||
| **vault** | `projects/<p>/vaults/<v>` (symlink) | tabla `vaults` | no (datos fuera del repo) |
|
||||
| **project** | `projects/<p>/` | tabla `projects` | no (vive dentro de fn_registry) |
|
||||
| **playground** | `<artefacto_padre>/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).
|
||||
@@ -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
|
||||
|
||||
```
|
||||
<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
|
||||
```
|
||||
Reference in New Issue
Block a user