Desarrollo local y pruebas

El desarrollo local de Éclair no pide Composer, ni base de datos, ni contenedor: basta con PHP 8.1 o superior. En esta lección ejecutas el sitio en tu máquina, lanzas las 550 comprobaciones automáticas, construyes el archivo de distribución, mides con Lighthouse y pruebas el conector MCP antes de tocar un sitio en línea.

Lanzar Éclair en desarrollo local

git clone https://github.com/Jacckisback/eclair-cms.git
cd eclair-cms
PHP_CLI_SERVER_WORKERS=4 php -S localhost:8000 -t eclair tools/router.php

La opción -t eclair convierte la carpeta eclair/ en la raíz del sitio, como la carpeta pública de un hosting. El script tools/router.php reproduce las reglas del .htaccess: 404 para app/, data/, cache/, los archivos ocultos y cualquier .php distinto de index.php, y ningún script ni página en media/. Sirve tal cual los archivos existentes y envía todo lo demás a index.php.

¿Por qué PHP_CLI_SERVER_WORKERS=4? Para verificar su dirección, el sitio se llama a sí mismo en /__eclair/ping. Con un solo proceso, el servidor integrado está ocupado con la petición en curso y no puede responder: la verificación falla y las redirecciones a la dirección oficial siguen desactivadas. PHP no admite varios procesos en Windows: usa WSL o acepta una dirección sin verificar en local.

Después abre http://localhost:8000: arranca el asistente de instalación, con el mismo plazo de 2 horas que en línea. Usa siempre la misma dirección (localhost o 127.0.0.1): es la que guarda la instalación. Tus datos locales van a eclair/data/, que Git ignora, igual que la caché, las imágenes subidas y eclair-config.php.

¿Cómo se lanzan las pruebas de Éclair?

php tests/run.php                  # unitarias + integración HTTP
# ✅ 550 vérifications réussies

php tests/run.php --unit           # solo unitarias, en pocos segundos
# ✅ 241 vérifications réussies

# La misma batería de pruebas sobre un archivo descomprimido
ECLAIR_TEST_ROOT=/tmp/archive/eclair php tests/run.php

Las herramientas del repositorio muestran sus mensajes en francés, como la línea «550 vérifications réussies» (550 comprobaciones superadas). Las pruebas no tocan tu sitio de desarrollo local: los datos de las pruebas unitarias van a la carpeta temporal del sistema. Cada prueba HTTP copia eclair/ en esa misma carpeta, vacía sus datos, lanza php -S en un puerto al azar con cuatro procesos y tools/router.php, instala un sitio y después repite sus escenarios con curl. Si algo falla, se muestra la lista de comprobaciones fallidas y el comando termina con el código 1: se integra tal cual en una cadena de integración continua.

Desarrollar el asistente IA sin clave ni gasto

tests/fake-ai.php imita las API de Anthropic, OpenAI, FLUX e Ideogram. Las pruebas lo lanzan en un puerto local y escriben en su copia un eclair-config.php que define ECLAIR_AI_ENDPOINTS. Puedes reproducir este montaje para trabajar en la interfaz del asistente:

# Terminal 1: proveedores simulados (registro de peticiones en /tmp/fake-ai/log.jsonl)
mkdir -p /tmp/fake-ai
FAKE_AI_DIR=/tmp/fake-ai php -S 127.0.0.1:9999 tests/fake-ai.php

<?php
// eclair/eclair-config.php: el asistente habla con los proveedores simulados
defined('ECLAIR') || exit;
define('ECLAIR_AI_ENDPOINTS', ['anthropic' => 'http://127.0.0.1:9999', 'openai' => 'http://127.0.0.1:9999']);

El servidor simulado solo acepta sus claves de prueba, como sk-ant-test-0123456789, y reacciona a una palabra clave incluida en tu petición: ARTICLE (imagen y después borrador), EQUIPE (alta de un miembro) o PIEGE (texto malicioso), entre otras.

Construir el archivo de distribución

php tools/build.php
# ✓ Traductions : 6 langues compilées (eclair/app/lang)
# ✓ Empreintes : 126 fichiers (app/manifest.php)
# ✓ Archive : …/dist/eclair-cms-1.8.0.zip (479 Ko, 981 991 octets une fois décompressée)

La versión sale de la constante ECLAIR_VERSION de eclair/index.php. El script vuelve a compilar las traducciones, calcula la huella SHA-256 de cada archivo (sus primeros 128 bits) en app/manifest.php, la base del control de integridad, y después crea dist/eclair-cms-<version>.zip. Dentro del ZIP, el PHP se compacta con php -w, las vistas de la administración se comprimen (.php.gz, que se leen con zlib) y el JavaScript y el CSS de la administración se aligeran. El renderizado público sigue idéntico byte a byte. El contenido de data/, cache/ y media/ y tu eclair-config.php quedan fuera, mientras que se añaden LISEZ-MOI.txt, LICENSE.txt y THIRD-PARTY-NOTICES.txt. Sin la extensión zip, no se crea ningún ZIP.

Capturar el renderizado y medir con Lighthouse

npm install -g lighthouse              # Node.js 22 o superior
php tools/capture.php                  # huellas del renderizado → tests/fixtures/public-<version>.json
php tools/capture.php --lighthouse     # Lighthouse en móvil → tests/fixtures/lighthouse-<version>.json

tools/capture.php sirve los cuatro sitios de referencia de tests/fixtures/sites/ (blog, business, freelance, landing) y guarda la huella de cada página, primero para un visitante y después con una sesión de administración, además del HTML de cada bloque y de los archivos CSS y JS públicos. tests/run.php compara el renderizado actual con public-1.6.0.json: una versión nueva no debe cambiar ni un byte del sitio público. La opción --reinstall vuelve a crear los sitios de partida y, por tanto, huellas nuevas: las referencias existentes dejan de valer.

Con --lighthouse, la herramienta mide en móvil la página de inicio y un artículo del sitio «business», la página «landing» y después la página de inicio con cuatro direcciones de arte, y se queda con la mediana de tres pasadas. Las variables LIGHTHOUSE y CHROME_PATH indican el comando y el navegador. En Éclair 1.8, cada página medida obtiene 100 en las cuatro categorías, con un LCP de 779 a 885 ms, un CLS de 0 y un TBT de 0 a 17 ms.

Modo de depuración y eclair-config.php

Copia eclair/eclair-config.exemple.php con el nombre eclair-config.php, junto a index.php, y deja solo las líneas útiles. Este es el modelo, completado con la constante ECLAIR_SECRET:

<?php
defined('ECLAIR') || exit;

// Detalle de los errores y caché estática desactivada: solo mientras resuelves un problema.
define('ECLAIR_DEBUG', true);

// Datos fuera de la carpeta pública (mueve antes la carpeta «data»).
// define('ECLAIR_DATA', '/home/moncompte/eclair-data');

// Secreto adicional para la caja fuerte de las claves de API, antes de guardarlas.
// define('ECLAIR_SECRET', 'une-longue-phrase-secrète');

Sin modo de depuración, un error muestra la página «Oups, un court-circuit» (un texto fijo en francés) con una referencia de 8 caracteres. El detalle se anota en data/logs/errors.php y se puede ver en la página Seguridad, sección Últimos errores técnicos: es el método correcto en un sitio en línea, donde ECLAIR_DEBUG mostraría tus errores a los visitantes.

Probar el conector MCP con MCP Inspector

1. En la administración local, abre Ajustes › Asistente IA, activa Permitir conexiones MCP y guarda. Un aviso recuerda que Claude y ChatGPT exigen una dirección https; el Inspector, en cambio, acepta tu dirección local.
2. Comprueba el descubrimiento OAuth y el rechazo sin token con los dos primeros comandos de abajo.
3. Lanza el Inspector con la dirección del conector (tercer comando).
4. Conéctate desde el Inspector: lee el descubrimiento, se registra (Éclair acepta direcciones de retorno en http://localhost, 127.0.0.1 o [::1]) y abre la página de consentimiento de Éclair. Identifícate y haz clic en Permitir.
5. Lista las herramientas: get_site, search_content, get_content y find_media en lectura; create_draft y update_content en escritura, limitadas a 60 por hora y por conexión.

# Descubrimiento: recurso protegido y servidor de autorización
curl -s http://localhost:8000/.well-known/oauth-protected-resource

# Sin token: rechazo 401 que apunta al descubrimiento
curl -si -X POST http://localhost:8000/_eclair/mcp | grep -i www-authenticate
# WWW-Authenticate: Bearer resource_metadata="http://localhost:8000/.well-known/oauth-protected-resource"

# MCP Inspector, interfaz web
npx @modelcontextprotocol/inspector --server-url http://localhost:8000/_eclair/mcp --transport http

El conector de Éclair 1.8 anuncia las versiones 2025-11-25, 2025-06-18 y 2025-03-26 del protocolo. Para una prueba automatizable, el mismo comando con --cli y --method tools/list lista las herramientas en el terminal.

Para recordar

• El desarrollo local de Éclair cabe en un comando: PHP_CLI_SERVER_WORKERS=4 php -S localhost:8000 -t eclair tools/router.php.
• php tests/run.php repite 550 comprobaciones sobre copias, sin tocar tu sitio; --unit se limita a las 241 pruebas unitarias.
• php tools/build.php genera el archivo de distribución y reescribe app/manifest.php, la base del control de integridad.
• eclair-config.php contiene los ajustes avanzados; ECLAIR_DEBUG solo se queda activo mientras dura un diagnóstico.
• MCP Inspector prueba el conector en local, OAuth incluido, antes de Claude o ChatGPT.

Para saber más

• La arquitectura de Éclair: lo que ejercitan tus pruebas, petición a petición.
• Personalizar las plantillas del tema: modificar el renderizado y comprobarlo con estas herramientas.
• Entender el conector MCP: las seis herramientas y lo que la IA no puede hacer.
• Rendimiento: mantener 100 sobre 100: leer e interpretar una medición de Lighthouse.
• PHP: el servidor web interno y sus scripts de enrutamiento.
• Model Context Protocol: documentación de MCP Inspector, en inglés.

Todas las lecciones de la ruta