CLI y preparación para producción — Documentación de dhal

Documentación de dhal

Página 8 de 9

La CLI dhal se incluye con @rokadhq/dhal y puede ejecutarse mediante npx dhal.

Comandos principales

bash

npx dhal add
npx dhal init
npx dhal test-config
npx dhal migrate --check
npx dhal doctor
npx dhal doctor --fix --dry-run
npx dhal openapi inspect openapi.json
npx dhal openapi generate openapi.yaml
npx dhal readiness --production
npx dhal compat
npx dhal stability
npx dhal rules
npx dhal presets list
npx dhal replay fixtures.replay.json
npx dhal simulate fixtures.simulation.json
npx dhal report --output dhal.report.json
npx dhal release-check --target stable --require-build

Incorporación guiada del proyecto

bash

npx dhal add

dhal add detecta Express, Fastify, NestJS, Koa o Hono desde package.json, y npm, pnpm, Yarn o Bun desde el archivo de bloqueo. La ejecución predeterminada es de solo lectura: muestra un preset de framework, un dhal.json en modo de supervisión, un módulo de integración, el comando de instalación y las instrucciones de registro.

Después de revisarlo:

bash

npx dhal add --write

Opciones principales:

text

--framework <nombre>      Sobrescribe la detección
--config <ruta>           Ruta de configuración
--integration <ruta>      Ruta del módulo generado
--write                   Crea los archivos propuestos
--force                   Sobrescribe salidas generadas existentes

El comando nunca modifica automáticamente el código fuente existente.

Inicializar, validar y migrar

bash

npx dhal init
npx dhal test-config
npx dhal migrate --check

init crea una configuración genérica centrada en supervisión. test-config valida la configuración efectiva. migrate --check informa de migraciones sin cambiar archivos. Usa migrate --write solo después de revisar la propuesta.

Doctor y reparación conservadora

bash

npx dhal doctor
npx dhal doctor --fix --dry-run
npx dhal doctor --fix

doctor --fix tiene un alcance intencionadamente limitado. Puede crear una configuración de supervisión ausente, migrar una configuración compatible anterior a schemaVersion y crear dhal.json.bak antes de cambiar un archivo existente.

No activa automáticamente bloqueo, confianza de proxy, Redis, reputación, OpenTelemetry ni webhooks. Usa --dry-run para revisar y --no-backup solo cuando ya exista otro mecanismo de copia.

Presets de framework

bash

npx dhal presets list
npx dhal presets show nestjs-api
npx dhal presets apply hono-node-api --output dhal.hono.json

La versión 1.1 añade:

text

express-api
fastify-api
nestjs-api
koa-api
hono-node-api
node-http-api

Los presets operativos existentes, como starter, api-production, auth-hardened, strict-json-api, behind-proxy y observability, siguen disponibles. Revisa y valida toda salida generada.

Inspección OpenAPI

bash

npx dhal openapi inspect openapi.json
npx dhal openapi inspect openapi.yaml

JSON se analiza de forma estructural. YAML utiliza un escáner conservador para rutas, métodos, etiquetas, seguridad y tipos de contenido comunes. Convierte YAML complejo con anclas, fusiones o referencias externas a JSON.

La inspección clasifica autenticación, cargas multipart, webhooks, operaciones costosas, operaciones públicas y cuerpos JSON.

Generar políticas de supervisión desde OpenAPI

bash

npx dhal openapi generate openapi.yaml

Los parámetros se convierten en comodines:

text

/users/{userId}              -> /users/*
/orgs/{orgId}/users/{userId} -> /orgs/*/users/*

Todas las rutas generadas permanecen en monitor. Los perfiles existentes se conservan y se informan como preserve-existing.

bash

npx dhal openapi generate openapi.yaml --config dhal.json --write
npx dhal openapi generate openapi.json --output dhal.openapi.json

La primera forma crea una copia de seguridad. Usa --force para sustituir otra salida existente, --no-backup para omitir la copia y --default-max para cambiar el límite generado.

La política generada es una propuesta, no un modelo de autorización. Revisa métodos agrupados, clasificaciones, límites y supuestos de contenido antes de aplicar bloqueo.

Preparación, compatibilidad y estabilidad

bash

npx dhal readiness --production
npx dhal compat
npx dhal stability

La preparación evalúa la configuración de producción; compatibilidad muestra la matriz probada; estabilidad muestra el contrato de las superficies públicas. No sustituyen las pruebas de reproducción ni la revisión específica de la aplicación.

Reglas, reproducción y simulación

bash

npx dhal rules
npx dhal replay fixtures.replay.json
npx dhal simulate fixtures.simulation.json

Mantén fixtures de tráfico válido y malicioso en control de versiones. La promoción debe fallar si el tráfico válido se bloquea o los casos maliciosos dejan de coincidir.

Política de CI

bash

npx dhal ci

policy.ci puede impedir modos inseguros, exigir firma de webhooks, controlar reglas en monitor y rechazar supresiones caducadas.

Informe de soporte y comprobación de versión

bash

npx dhal report --output dhal.report.json
npx dhal release-check --target stable --require-build

Revisa los informes antes de compartirlos. No publiques secretos, credenciales, tokens ni tráfico sin redactar.

Lista de verificación de aplicación

Antes de activar block o strict, confirma:

versión exacta fijada y runtime compatible;
schemaVersion igual a "1";
cambios de incorporación u OpenAPI revisados;
validación, migración, doctor y preparación correctos;
fixtures válidos y maliciosos correctos;
Redis o Valkey compartido cuando haya varias instancias;
firma, redacción y cierre mediante close() configurados;
reversión a monitor documentada y probada.