Skip to content

Commit dec70cb

Browse files
MedalcodeMedalcode
committed
chore(docs): merge docs/agent-skills-ci into main
2 parents ecf82b2 + 5bdb79d commit dec70cb

52 files changed

Lines changed: 3070 additions & 1830 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.eslintrc.json‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -9,9 +9,9 @@
99
"sourceType": "module"
1010
},
1111
"rules": {
12-
"indent": ["error", 2],
13-
"linebreak-style": ["error", "unix"],
14-
"quotes": ["error", "double"],
12+
"indent": ["warn", 2],
13+
"linebreak-style": ["warn", "unix"],
14+
"quotes": ["warn", "double"],
1515
"semi": ["error", "always"],
1616
"no-unused-vars": "warn",
1717
"no-console": "off",

‎.gitattributes‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,7 @@
1-
# Auto detect text files and perform LF normalization
1+
* text=auto eol=lf
2+
src/**/* text eol=lf
3+
docs/**/* text eol=lf
4+
.github/**/* text eol=lf
5+
.husky/* text eol=lf
6+
.gitattributes text eol=lf# Auto detect text files and perform LF normalization
27
* text=auto

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
<!-- Por favor completa la plantilla para ayudar la revisión. -->
2+
3+
## Descripción
4+
- ¿Qué cambia y por qué?
5+
6+
## Tipo de cambio
7+
- [ ] Bugfix
8+
- [ ] Nueva feature
9+
- [ ] Documentación
10+
- [ ] Refactor
11+
12+
## Checklist
13+
- [ ] He seguido las guías de contribución (`docs/CONTRIBUTING.md`)
14+
- [ ] Ejecuté `npm run lint` y no quedan errores
15+
- [ ] Ejecuté `npm test` y pasaron todas las pruebas
16+
- [ ] Actualicé `docs/skills.md` si añadí/actualicé una skill
17+
- [ ] Documenté cambios breaking (si aplica)
18+
19+
## Notas para el revisor
20+
- Instrucciones para probar los cambios localmente, datos de ejemplo o comandos.

‎.github/workflows/ci.yml‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
name: CI
2+
3+
on:
4+
pull_request:
5+
branches: [ main ]
6+
push:
7+
branches: [ main ]
8+
9+
jobs:
10+
build-and-test:
11+
runs-on: ubuntu-latest
12+
steps:
13+
- name: Checkout code
14+
uses: actions/checkout@v4
15+
16+
- name: Use Node.js
17+
uses: actions/setup-node@v4
18+
with:
19+
node-version: 18
20+
21+
- name: Cache node modules
22+
uses: actions/cache@v4
23+
with:
24+
path: ~/.npm
25+
key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
26+
restore-keys: |
27+
${{ runner.os }}-node-
28+
29+
- name: Install dependencies
30+
run: npm ci
31+
32+
- name: Lint
33+
run: npm run lint
34+
35+
- name: Run tests with coverage
36+
run: npm test -- --coverage
37+
38+
- name: Upload coverage artifact
39+
if: always()
40+
uses: actions/upload-artifact@v4
41+
with:
42+
name: coverage-report
43+
path: ./coverage

‎.github/workflows/deploy-netlify.yml‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
name: Deploy to Netlify
2+
3+
on:
4+
push:
5+
branches: [ main ]
6+
7+
jobs:
8+
build-and-deploy:
9+
runs-on: ubuntu-latest
10+
steps:
11+
- name: Checkout
12+
uses: actions/checkout@v4
13+
14+
- name: Use Node.js
15+
uses: actions/setup-node@v4
16+
with:
17+
node-version: 18
18+
19+
- name: Install dependencies
20+
run: npm ci
21+
22+
- name: Build
23+
run: npm run build
24+
25+
- name: Deploy to Netlify
26+
env:
27+
NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
28+
NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}
29+
run: |
30+
npx netlify-cli deploy --prod --dir=dist --site=$NETLIFY_SITE_ID --auth=$NETLIFY_AUTH_TOKEN

‎.husky/pre-commit‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
#!/bin/sh
2+
. "$(dirname "$0")/_/husky.sh"
3+
4+
npx lint-staged

‎README.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,8 @@
44
[![Status](https://img.shields.io/badge/Status-Stable-green)](https://github.com/Medalcode/NetOpsToolkit)
55
[![Deploy](https://img.shields.io/badge/Deploy-Netlify-00C7B7)](https://netops-toolkit.netlify.app)
66
[![Tests](https://img.shields.io/badge/Tests-20%20passing-success)](https://github.com/Medalcode/NetOpsToolkit)
7+
[![CI](https://github.com/Medalcode/NetOpsToolkit/actions/workflows/ci.yml/badge.svg)](https://github.com/Medalcode/NetOpsToolkit/actions)
8+
[![Netlify Status](https://api.netlify.com/api/v1/badges/PUT-YOUR-BADGE-HERE/deploy-status)](https://app.netlify.com/sites/YOUR-SITE/deploys)
79

810
> **"La Navaja Suiza para Ingenieros de Red"**
911
>
@@ -78,6 +80,15 @@ npm run build
7880
- [CHANGELOG.md](CHANGELOG.md) - Historial de cambios
7981
- [TODO.md](TODO.md) - Tareas pendientes y roadmap
8082
- [LICENSE](LICENSE) - Licencia MIT
83+
- [Docs (agent & skills)](docs) - Guía para agentes, catálogo de skills y prácticas de CI/CD
84+
85+
## Docs & PR
86+
87+
- Documentación añadida en [docs/](docs) — `agent.md`, `skills.md`, `CONTRIBUTING.md`.
88+
- Pull request con estos cambios: https://github.com/Medalcode/NetOpsToolkit/pull/1
89+
90+
Nota: el badge de Netlify es un placeholder; añade `NETLIFY_BADGE_ID` o actualiza la URL del badge con el ID de tu sitio en Netlify.
91+
8192

8293
## 🧪 Testing
8394

‎docs/CONTRIBUTING.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# Contribuir a NetOps Toolkit
2+
3+
Gracias por querer contribuir. Este documento resume el flujo sugerido,
4+
normas de calidad y pasos mínimos antes de enviar un PR.
5+
6+
1. Fork y crea una rama descriptiva: `feature/<descripcion>` o `fix/<descripcion>`.
7+
2. Sigue Conventional Commits para los mensajes de commit.
8+
3. Ejecuta linters y tests localmente:
9+
10+
```bash
11+
npm ci
12+
npm run lint
13+
npm test
14+
```
15+
16+
4. Mantén la cobertura y añade tests para la lógica nueva.
17+
5. Si añades una nueva "skill", actualiza `docs/skills.md` con el frontmatter correspondiente.
18+
6. Añade documentación y notas de migración si cambias APIs o contratos.
19+
20+
Hooks y calidad de código
21+
22+
- El proyecto usa `husky` + `lint-staged`. Instala los hooks con:
23+
24+
```bash
25+
npm run prepare
26+
```
27+
28+
- El pre-commit ejecutará los linters y formateadores configurados.
29+
30+
Revisión y merge
31+
32+
- Abre un PR con descripción clara y checklist completada.
33+
- Los PRs deben pasar CI (`.github/workflows/ci.yml`) antes de merge.
34+
35+
Gracias — tu contribución mejora la herramienta para toda la comunidad.

‎docs/agent.md‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
---
2+
id: agent-manifest-v1
3+
version: 1.0.0
4+
language: es
5+
generated_by: agent-automation
6+
description: >-
7+
Documento maestro que describe el agente/entorno de ejecución para
8+
NetOpsToolkit: arquitectura, catálogo de `skills`, contratos de invocación,
9+
políticas de seguridad y checklist de despliegue.
10+
---
11+
12+
# Agent Manifest — NetOpsToolkit
13+
14+
## Propósito
15+
16+
Este documento describe cómo un "agent" (humano o automatizado) debe
17+
descubrir, validar e invocar las capacidades (`skills`) del proyecto.
18+
19+
## Arquitectura (resumen)
20+
21+
- Frontend SPA construido con Vite, Tailwind y módulos ES (entry: `src/js/main.js`).
22+
- Herramientas organizadas en `src/js/tools/` y wrappers de plataforma en `src/js/platform/`.
23+
- Serverless: Netlify Functions en `netlify/functions/` (ej. `geo-ip.js`).
24+
- Tests: Jest (`tests/`).
25+
26+
## Catálogo de skills
27+
28+
El catálogo machine-readable se encuentra en `docs/skills.md`.
29+
Los agentes deben leer el frontmatter YAML para mapear `skill.id` a la
30+
implementación adecuada (módulo lazy-loaded o función serverless).
31+
32+
## Contrato de invocación (ejemplos)
33+
34+
1) Invocar skill en cliente (módulo JS):
35+
36+
```js
37+
import('./src/js/tools/ip-lookup.js').then(({run})=>{
38+
return run({clientIp: '1.2.3.4'})
39+
})
40+
```
41+
42+
2) Invocar skill como API (Netlify Function):
43+
44+
Request POST /.netlify/functions/skill-proxy
45+
Payload:
46+
```json
47+
{ "skill": "ip-lookup", "input": { "clientIp": "1.2.3.4" } }
48+
```
49+
50+
Response esperado (estándar):
51+
```json
52+
{ "status": "ok", "skill": "ip-lookup", "result": { ... } }
53+
```
54+
55+
## Requisitos de runtime y secrets
56+
57+
- Node >=16 para funciones serverless y scripts de build.
58+
- Secretos (añadir en Netlify / GitHub Secrets): `NETLIFY_AUTH_TOKEN`, `NETLIFY_SITE_ID`, `SENTRY_DSN` (si aplica).
59+
60+
## CI/CD
61+
62+
- CI: `npm run lint`, `npm test -- --coverage` en PRs.
63+
- Deploy: build y despliegue automático a Netlify en `main` (workflow incluido).
64+
65+
## Observabilidad y errores
66+
67+
- Integrar Sentry/Roweball para errores client-side si se decide.
68+
- Enviar métricas vitales y eventos de uso desde `src/js/analytics.js`.
69+
70+
## Seguridad
71+
72+
- Mantener `netlify.toml` y `public/_headers` con CSP y headers.
73+
- Revisar dependencias periódicamente (`npm audit`) y actualizar.
74+
75+
## Checklist de despliegue (antes de merge a `main`)
76+
77+
- [ ] Lint limpio (`npm run lint`).
78+
- [ ] Tests pasando con coverage aceptable (`npm test`).
79+
- [ ] Actualizar `docs/skills.md` si se añade/actualiza un skill.
80+
- [ ] Revisar `netlify.toml` y variables de entorno.
81+
82+
## Onboarding para contributors
83+
84+
- Añadir nueva herramienta: crear module en `src/js/tools/`, tests en `tests/`, y entry en `docs/skills.md`.
85+
- Seguir Conv. Commits y abrir PR con descripción y screenshots si aplica.

‎docs/skills.md‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
---
2+
id: skills-catalog-v1
3+
version: 1.0.0
4+
language: es
5+
generated_by: agent-automation
6+
description: >-
7+
Catálogo machine-readable de "skills" (capacidades) disponibles en el
8+
proyecto NetOpsToolkit. Cada entrada contiene metadata que permite a
9+
agentes y pipelines descubrir, validar e invocar funcionalidades.
10+
---
11+
12+
# Catálogo de Skills
13+
14+
## Formato
15+
16+
Cada skill tiene YAML frontmatter con los campos mínimos:
17+
18+
- `id` (string): identificador único (kebab-case)
19+
- `name` (string): nombre legible
20+
- `description` (string): breve explicación
21+
- `capabilities` (array): lista de capacidades / tags
22+
- `inputs` (array): esquema simplificado de entradas (name, type, required)
23+
- `outputs` (array): esquema simplificado de salidas (name, type)
24+
- `runtime_requirements` (object): requisitos para ejecución (node, env vars)
25+
- `owner` (string): responsable / equipo
26+
- `version` (string): semver
27+
28+
Ejemplo de skill (registro):
29+
30+
---
31+
id: ip-lookup
32+
name: Búsqueda IP pública
33+
description: Devuelve información geolocalizada y metadata de la IP pública.
34+
capabilities:
35+
- geo
36+
- public-ip
37+
inputs:
38+
- name: clientIp
39+
type: string
40+
required: false
41+
outputs:
42+
- name: ip
43+
type: string
44+
- name: country
45+
type: string
46+
- name: asn
47+
type: string
48+
runtime_requirements:
49+
node: ">=16"
50+
env:
51+
- NETLIFY_API_KEY (optional)
52+
owner: netops-team
53+
version: 1.0.0
54+
---
55+
56+
## Skills registrados (ejemplos iniciales)
57+
58+
- `ip-lookup` — Info de IP pública y geo (usa `netlify/functions/geo-ip.js`).
59+
- `dns-lookup` — Resolución y análisis DNS (core en `src/js/dns-core.js`).
60+
- `bandwidth-calc` — Calculadora de ancho de banda (herramienta en `src/js/tools/bandwidth.js`).
61+
- `oui-lookup` — Búsqueda de OUI/Organización (herramienta `src/js/tools/oui.js`).
62+
63+
## Buenas prácticas para añadir nuevas skills
64+
65+
- Crear una entrada YAML en `docs/skills.md` con `id` único.
66+
- Implementar la lógica en `src/js/tools/<skill>.js` y exponer `init<Skill>` y una API pura exportable para tests.
67+
- Añadir tests en `tests/` que cubran la lógica del core.
68+
- Documentar variables de entorno necesarias y permisos para serverless en `agent.md`.
69+
70+
## Consumo por agentes
71+
72+
Un agente puede parsear el frontmatter YAML para obtener el catálogo de
73+
`skills` y mapear `skill.id` a los módulos/lambdas correspondientes. Las
74+
políticas de validación se indican en `runtime_requirements`.

0 commit comments

Comments
 (0)