deploy(telemetry): auto-publish latest metrics & social preview to gh-pages [skip ci] e21aa76

Author: github-actions[bot]

.agents/rules/AGENTS.md

@@ -0,0 +1,18 @@
+# Reglas — GitHub Telemetry Engine
+
+## 1. Arquitectura (SRP)
+- **`scripts/update_metrics.py`**: Extractor puro. Filtra `--source` (`isFork: false`), auto-detecta `User`/`Org` y exporta `data.json`. Prohibido mutar HTML.
+- **`index.html`**: Hidratación reactiva con `fetch('data.json')`. Cero datos hardcodeados. Tabla sortable interactiva.
+- **`scripts/generate_preview.py`**: Renderiza `og-preview.png` (2400x1260 px) vía Playwright sobre `templates/share.html`.
+- **Despliegue**: Solo a rama aislada `gh-pages`. `main`/`dev` sin commits de bots.
+
+## 2. Estilo Visual (Swiss Minimalist)
+- **Colores planos**: `#1e3a8a`, `#046a38`, `#b45309`, `#09090b`, `#f8fafc`. Sin degradados.
+- **Bordes 1px**: `border-zinc-300` / `border-zinc-200`.
+- **Tipografía**: `Inter` (copies) + `JetBrains Mono` (métricas).
+- **Branding**: Logo compacto `{{shellaquiles.org}}` y footer fijo con atribución a Shellaquiles.
+
+## 3. Telemetría y Versión
+- **Bots**: Excluir cuentas `[bot]` y `actions-user`.
+- **Antigüedad**: Computada automáticamente desde el repo más antiguo.
+- **Versión**: `VERSION` es la fuente única de verdad. Sincronizar en `CHANGELOG.md`.

.agents/workflows/sync_metrics.md

@@ -0,0 +1,11 @@
+---
+name: sync-metrics
+description: Actualiza métricas de GitHub, data.json y og-preview.png.
+---
+
+# Sync Metrics
+
+1. `gh auth status`
+2. `make sync`
+3. `make preview`
+4. `make dev`

.gitignore

@@ -0,0 +1,19 @@
+# Environment & Local Configuration
+.env
+.env.local
+
+# Python Cache & Virtual Environments
+__pycache__/
+*.py[cod]
+*$py.class
+.venv/
+venv/
+ENV/
+
+# Operating System & IDE Artifacts
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/
+*.swp
+*.swo

.nojekyll

@@ -0,0 +1,43 @@
+# Changelog
+
+Todas las modificaciones notables de este proyecto se documentan en este archivo.
+
+El formato se basa en [Keep a Changelog](https://keepachangelog.com/es-ES/1.1.0/) y este proyecto se adhiere a [Semantic Versioning](https://semver.org/lang/es/).
+
+---
+
+## [1.0.0] - 2026-08-27
+
+### Added
+- **Extractor autónomo en Python (`update_metrics.py`)**:
+  - Autodescubrimiento de repositorios públicos mediante GitHub CLI (`gh`).
+  - Auto-detección del tipo de cuenta (`User` vs `Organization`) vía GitHub API.
+  - Filtro nativo de repositorios originales con `--source` y descarte automático de forks (`isFork: false`).
+  - Agregación y normalización cualitativa de fuentes de tráfico (*referrers*: LinkedIn, Telegram, Google Search, X, GitHub).
+  - Filtro automático de cuentas de automatización y bots (`dependabot`, `github-actions`, `[bot]`).
+  - Cálculo dinámico de la fecha más antigua (`active_since`) a partir de la fecha de creación de los repositorios.
+  - Jerarquía de excepciones de dominio (`TelemetryError`, `GitHubCLIError`, `ConfigurationError`) y timeouts de ejecución.
+- **Frontend SPA Reactivo (`index.html`)**:
+  - Diseño bajo el **Swiss Minimalist System** (colores institucionales planos, rejillas de 1px y tipografía `Inter` + `JetBrains Mono`).
+  - Hidratación dinámica asíncrona mediante `fetch('data.json')`.
+  - Gráficos interactivos con Chart.js (Radar de Ecosistema multieje).
+  - Tabla consolidada de Stats Globales interactiva con ordenamiento en tiempo real y columna de fecha `Creado`.
+  - Catálogo técnico por proyecto y cuadro de honor de colaboradores con avatares.
+  - Branding oficial compacto `{{shellaquiles.org}}` y footer fijo con blur (`backdrop-filter: blur(4px)`).
+  - Crédito institucional permanente de origen hacia Shellaquiles en el footer.
+- **Configuración Declarativa Minimalista (Zero-Config)**:
+  - Soporte de configuración jerárquica vía `config.json` (solo requiere `"target": "USUARIO"`) y variables de entorno (`.env.example`).
+- **Pipeline de Despliegue Limpio CI/CD (`.github/workflows/sync_metrics.yml`)**:
+  - Tarea programada diaria (06:00 UTC) y ejecución manual (`workflow_dispatch`).
+  - Publicación a la rama huérfana aislada `gh-pages` con `force_orphan: true`, manteniendo `main` y `dev` con 0 commits de bots.
+- **Tarjeta Social & Motor OpenGraph (`share.html` & `generate_preview.py`)**:
+  - Lienzo oficial de 1200 × 630 px con proporciones estándar para Twitter/X, LinkedIn y Facebook.
+  - Composición de alto impacto combinando 4 KPIs resumidos y la Matriz Técnica completa con iconos y stacks.
+  - Script automatizado con Playwright (`make preview`) para exportación a resolución Retina 2x (`2400 × 1260 px`) con cierre limpio del servidor.
+  - Integración de metadatos `<meta property="og:image">` y Twitter Card en `index.html`.
+  - Banner interactivo de replicación / Call to Action en el footer para fork en 1-click.
+- **Herramientas de Desarrollo Local**:
+  - `Makefile` con objetivos `dev`, `sync`, `preview`, `serve` y `clean` con detección automática de `.venv`.
+  - `.gitignore` para desacoplar los artefactos de runtime `data.json` y `og-preview.png` del código fuente.
+- **Documentación**:
+  - `README.md` estandarizado con guía Zero-Config en 4 pasos y diagramas de flujo en Mermaid.

CHANGELOG.md

@@ -0,0 +1,75 @@
+# ── CONFIGURACIÓN DEL ENTORNO & PYTHON ─────────────────────────────────────────
+VENV_DIR  := .venv
+VENV_BIN  := $(shell if [ -d "$(VENV_DIR)/bin" ]; then echo "$(VENV_DIR)/bin/"; fi)
+PYTHON    := $(VENV_BIN)python3
+PIP       := $(VENV_BIN)pip
+PORT      := 8000
+
+# ── ESTILOS & COLORES ANSI ───────────────────────────────────────────────────
+BOLD      := \033[1m
+DIM       := \033[2m
+RESET     := \033[0m
+BLUE      := \033[38;5;33m
+EMERALD   := \033[38;5;42m
+AMBER     := \033[38;5;214m
+CYAN      := \033[38;5;51m
+RED       := \033[38;5;196m
+GRAY      := \033[38;5;244m
+
+.PHONY: all help dev sync preview serve setup venv clean
+
+all: help
+
+## ── AYUDA & COMANDOS ──────────────────────────────────────────────────────────
+help:
+	@printf "\n"
+	@printf "  $(BOLD)$(EMERALD)shell$(RESET)$(BOLD)aquiles$(RESET)$(RED).org$(RESET) $(DIM)• Telemetry & Stats Engine$(RESET)\n"
+	@printf "  $(GRAY)━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━$(RESET)\n"
+	@printf "  Dashboard de métricas públicas de GitHub: repositorios, tráfico,\n"
+	@printf "  colaboradores y tarjeta social generada automáticamente en CI/CD.\n"
+	@printf "  $(GRAY)━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━$(RESET)\n"
+	@printf "  $(BOLD)Uso:$(RESET) make $(CYAN)<comando>$(RESET)\n\n"
+	@printf "  $(BOLD)Comandos Principales:$(RESET)\n"
+	@printf "    $(CYAN)make dev$(RESET)       $(GRAY)→$(RESET) Sincroniza métricas y levanta servidor en http://localhost:$(PORT)\n"
+	@printf "    $(CYAN)make sync$(RESET)      $(GRAY)→$(RESET) Extrae telemetría de GitHub y genera $(BOLD)data.json$(RESET)\n"
+	@printf "    $(CYAN)make preview$(RESET)   $(GRAY)→$(RESET) Genera tarjeta para redes sociales ($(BOLD)og-preview.png$(RESET))\n"
+	@printf "    $(CYAN)make serve$(RESET)     $(GRAY)→$(RESET) Inicia servidor HTTP local en puerto $(PORT)\n\n"
+	@printf "  $(BOLD)Entorno & Mantenimiento:$(RESET)\n"
+	@printf "    $(CYAN)make setup$(RESET)     $(GRAY)→$(RESET) Crea entorno virtual e instala Playwright/Chromium\n"
+	@printf "    $(CYAN)make clean$(RESET)     $(GRAY)→$(RESET) Limpia artefactos generados ($(BOLD)data.json$(RESET), $(BOLD)og-preview.png$(RESET), cachés)\n"
+	@printf "  $(GRAY)━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━$(RESET)\n\n"
+
+## ── FLUJOS DE DESARROLLO ─────────────────────────────────────────────────────
+dev: sync serve
+
+sync:
+	@printf "  $(BLUE)📡 Extrayendo telemetría de GitHub vía gh CLI...$(RESET)\n"
+	@$(PYTHON) scripts/update_metrics.py
+	@printf "  $(EMERALD)✔ data.json actualizado correctamente.$(RESET)\n"
+
+preview:
+	@printf "  $(AMBER)📸 Renderizando tarjeta de alta resolución (2x Retina)...$(RESET)\n"
+	@$(PYTHON) scripts/generate_preview.py
+
+serve:
+	@printf "\n  $(BOLD)$(EMERALD)🚀 Servidor local activo:$(RESET) $(CYAN)http://localhost:$(PORT)$(RESET)\n"
+	@printf "  $(DIM)   Presiona Ctrl+C para detener el servidor.$(RESET)\n\n"
+	@$(PYTHON) -m http.server $(PORT)
+
+## ── SETUP & ENTORNO VIRTUAL ──────────────────────────────────────────────────
+setup: venv
+	@printf "  $(BLUE)📦 Instalando dependencias de Playwright...$(RESET)\n"
+	@$(PIP) install --quiet playwright
+	@$(VENV_BIN)playwright install chromium
+	@printf "  $(EMERALD)✔ Entorno virtual y navegadores listos en $(VENV_DIR).$(RESET)\n"
+
+venv:
+	@if [ ! -d "$(VENV_DIR)" ]; then \
+		printf "  $(BLUE)⚙️ Creando entorno virtual en $(VENV_DIR)...$(RESET)\n"; \
+		python3.11 -m venv $(VENV_DIR) 2>/dev/null || python3 -m venv $(VENV_DIR); \
+	fi
+
+clean:
+	@rm -f data.json og-preview.png
+	@find . -type d -name "__pycache__" -exec rm -rf {} + 2>/dev/null || true
+	@printf "  $(EMERALD)🧹 Artefactos temporales y cachés eliminados.$(RESET)\n"

Makefile

@@ -0,0 +1,140 @@
+# shellaquiles/stats
+
+[![Demo en vivo](https://img.shields.io/badge/Demo_en_vivo-GitHub_Pages-22c55e.svg?style=flat-square&logo=github&logoColor=white)](https://shellaquiles.github.io/stats/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+[![Python 3.10+](https://img.shields.io/badge/Python-3.10+-3776AB.svg?style=flat-square&logo=python&logoColor=white)](https://www.python.org/)
+[![Chart.js](https://img.shields.io/badge/Chart.js-FF6384.svg?style=flat-square&logo=chartdotjs&logoColor=white)](https://www.chartjs.org/)
+[![Playwright](https://img.shields.io/badge/Playwright-2EAD33.svg?style=flat-square&logo=playwright&logoColor=white)](https://playwright.dev/)
+[![GitHub Actions](https://img.shields.io/badge/CI%2FCD-GitHub_Actions-2088FF.svg?style=flat-square&logo=github-actions&logoColor=white)](https://github.com/features/actions)
+
+Dashboard web estático y automático para visualizar la **Huella Digital** y métricas de proyectos en GitHub (stars, forks, clones, commits, visitas y colaboradores). 
+
+Impulsado por la comunidad de **[shellaquiles.org](https://shellaquiles.org)**.
+
+<p align="center">
+  <a href="https://shellaquiles.github.io/stats/">
+    <img src="https://img.shields.io/badge/🚀_VER_DEMO_EN_VIVO-shellaquiles.github.io%2Fstats-22c55e?style=for-the-badge&logo=githubpages&logoColor=white" alt="Ver Demo en Vivo" />
+  </a>
+</p>
+
+> 💡 **Tu URL personal tras hacer Fork:** `https://<TU-USUARIO>.github.io/stats/`  
+> *(Por ejemplo, si tu usuario es `@pixelead0`, tu página se publicará en `https://pixelead0.github.io/stats/`).*
+
+---
+
+## Crea tu propio dashboard de estadísticas en 3 minutos
+
+Solo necesitas hacer un fork. El sistema detecta tu usuario en automático y publica tus métricas sin que tengas que tocar código:
+
+### 1. Haz Fork
+Haz clic en el botón **Fork** arriba a la derecha para copiar el repo a tu cuenta u organización.
+
+### 2. Activa GitHub Pages
+1. Ve a **Settings** > **Pages** en tu repo (o entra a `https://github.com/<TU_USUARIO>/stats/settings/pages`).
+2. En **Build and deployment** > **Source**, elige **Deploy from a branch**.
+3. En **Branch**, selecciona **`gh-pages`** y carpeta `/(root)`.
+4. Guarda los cambios.
+
+*(Nota: Si la rama `gh-pages` aún no aparece, se creará sola al terminar el paso 3. Para más detalles puedes ver la [documentación oficial de GitHub Pages](https://docs.github.com/es/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site)).*
+
+### 3. Corre la sincronización inicial
+1. Ve a la pestaña **Actions** en tu repo.
+2. Si los workflows están pausados, presiona el botón verde para activarlos (*"I understand my workflows, go ahead and enable them"*).
+3. Selecciona **`Auto-Sync Telemetry & Deploy to GitHub Pages`** a la izquierda.
+4. Haz clic en **Run workflow** > **Run workflow** (ver [cómo ejecutar workflows manualmente](https://docs.github.com/es/actions/managing-workflow-runs/manually-running-a-workflow)).
+
+### 4. Consulta tus resultados en vivo
+
+Cuando el workflow termine de ejecutarse (tarda ~1 minuto):
+
+1. **Tu Dashboard público**: Estará publicado en:
+   ```text
+   https://<TU_USUARIO>.github.io/stats/
+   ```
+2. **Tu Tarjeta Social**: Se habrá generado la miniatura `og-preview.png` (2400x1260 px) para compartir en redes.
+3. **Historial de ejecuciones**: Puedes ver el estado de cada corrida en la pestaña **Actions** de tu repositorio.
+
+> 📌 **Tip:** Agrega tu enlace `https://<TU_USUARIO>.github.io/stats/` en la sección **About** (en el engrane ⚙️ a la derecha de la portada de tu repo en GitHub) y marca la casilla *"Use your GitHub Pages website"*. Así tú y tus visitantes podrán entrar con 1 solo clic.
+
+A partir de este momento, tus métricas se actualizarán en automático todos los días a las **06:00 UTC**.
+
+---
+
+## ¿Qué incluye el dashboard?
+
+GitHub muestra tu actividad reciente, pero no te da una vista global del impacto de tus proyectos. Este dashboard genera una página web pública y ligera con:
+
+- **Huella Digital**: Radar multieje con el balance de Stars, Forks, Commits, Clones y Visitas.
+- **Stats Globales**: Tabla interactiva para ordenar tus repositorios por cualquier métrica o fecha de creación.
+- **Por Repositorio**: Tarjetas individuales con stack técnico y enlaces a código/demos.
+- **Colaboradores y Core Team**: Reconocimiento a quienes aportan código a tus repos (sin bots).
+- **Captura para Redes Sociales**: Genera en automático una tarjeta `og-preview.png` en alta resolución (2400x1260 px) para compartir en Twitter/X o LinkedIn.
+- **Zero-Config**: Filtra en automático tus repos públicos propios (`type=source`) y se actualiza solo cada 24 horas vía GitHub Actions sin costo de servidores.
+
+---
+
+## Desarrollo local
+
+Si quieres probarlo en tu máquina:
+
+```bash
+# 1. Clonar
+git clone https://github.com/<TU_USUARIO>/stats.git
+cd stats
+
+# 2. Correr servidor local (http://localhost:8000)
+make dev
+
+# 3. Generar la captura para redes
+make preview
+```
+
+---
+
+## Arquitectura
+
+```mermaid
+flowchart LR
+    GH[GitHub API] --> PY[scripts/update_metrics.py]
+    PY --> DATA[data.json]
+    DATA --> HTML[index.html]
+    DATA --> SHOT[scripts/generate_preview.py]
+    SHOT --> IMG[og-preview.png]
+    HTML --> GHP[gh-pages]
+    IMG --> GHP
+```
+
+```text
+├── .github/workflows/sync_metrics.yml   # Automatización CI/CD
+├── scripts/
+│   ├── update_metrics.py               # Extractor de datos (GitHub API)
+│   └── generate_preview.py             # Generador de tarjeta social (Playwright)
+├── templates/
+│   └── share.html                      # Plantilla para la captura social
+├── index.html                          # Dashboard web interactivo
+├── Makefile                            # Comandos de desarrollo local
+├── VERSION                             # Versión oficial (1.0.0)
+├── CHANGELOG.md                        # Historial de cambios
+└── README.md                           # Documentación del proyecto
+```
+
+- **Extractor**: Python puro con GitHub CLI (`gh`). Filtra forks (`--source`), auto-detecta usuario/org y calcula antigüedad.
+- **Frontend**: HTML5, Vanilla CSS y Vanilla JS. Sin frameworks pesados. Gráficos con Chart.js e iconos Lucide.
+- **Captura Social**: Playwright headless renderizando `templates/share.html` a escala 2x Retina.
+- **Despliegue**: GitHub Actions publicando a rama huérfana `gh-pages`.
+
+---
+
+## Sobre Shellaquiles
+
+Este proyecto es parte de las herramientas de código abierto desarrolladas por la comunidad de **[shellaquiles.org](https://shellaquiles.org)**. Si te gusta el desarrollo de herramientas de terminal, CLI y utilidades para devs, únete a la comunidad:
+
+- Web: [https://shellaquiles.org](https://shellaquiles.org)
+- GitHub: [https://github.com/shellaquiles](https://github.com/shellaquiles)
+- Otros proyectos: `cron-quiles`, `tribuTACOS`, `pandocquiles`, `KARNITAS`.
+
+---
+
+## Licencia
+
+MIT © Shellaquiles.

README.md

@@ -0,0 +1 @@
+1.0.0