CLI et préparation à la production — Documentation dhal

Documentation dhal

Page 8 sur 9

La CLI dhal est incluse dans @rokadhq/dhal et s’exécute avec npx dhal.

Commandes 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

Intégration guidée du projet

bash

npx dhal add

dhal add détecte Express, Fastify, NestJS, Koa ou Hono depuis package.json, ainsi que npm, pnpm, Yarn ou Bun depuis le fichier de verrouillage. L’exécution par défaut est en lecture seule : elle prévisualise un préréglage de framework, un dhal.json en mode surveillance, un module d’intégration, la commande d’installation et les instructions d’enregistrement.

Après vérification :

bash

npx dhal add --write

Options principales :

text

--framework <nom>         Remplace la détection
--config <chemin>         Chemin de configuration
--integration <chemin>    Chemin du module généré
--write                   Crée les fichiers proposés
--force                   Écrase les sorties générées existantes

La commande ne modifie jamais automatiquement le code source existant.

Initialiser, valider et migrer

bash

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

init crée une configuration générique centrée sur la surveillance. test-config valide la configuration effective. migrate --check signale les migrations sans modifier les fichiers. Utilisez migrate --write uniquement après vérification.

Doctor et réparation prudente

bash

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

doctor --fix a volontairement une portée limitée. Il peut créer une configuration de surveillance manquante, migrer une configuration compatible antérieure à schemaVersion et créer dhal.json.bak avant de modifier un fichier existant.

Il n’active pas automatiquement le blocage, la confiance proxy, Redis, la réputation, OpenTelemetry ou les webhooks. Utilisez --dry-run pour prévisualiser et --no-backup uniquement si une autre sauvegarde existe.

Préréglages 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 version 1.1 ajoute :

text

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

Les préréglages existants, notamment starter, api-production, auth-hardened, strict-json-api, behind-proxy et observability, restent disponibles. Vérifiez et validez toute sortie générée.

Inspection OpenAPI

bash

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

Le JSON est analysé structurellement. Le YAML utilise un scanner prudent pour les chemins, méthodes, étiquettes, déclarations de sécurité et types de contenu courants. Convertissez en JSON les documents YAML complexes utilisant ancres, fusions ou références externes.

L’inspection classe l’authentification, les chargements multipart, les webhooks, les opérations coûteuses, les opérations publiques et les corps JSON.

Générer une politique de surveillance depuis OpenAPI

bash

npx dhal openapi generate openapi.yaml

Les paramètres sont convertis en jokers :

text

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

Toutes les routes générées restent en monitor. Les profils existants sont préservés et signalés comme preserve-existing.

bash

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

La première forme crée une sauvegarde. Utilisez --force pour remplacer une autre sortie existante, --no-backup pour supprimer la sauvegarde et --default-max pour modifier la limite générée.

La politique générée est une proposition de sécurité, pas un modèle d’autorisation. Vérifiez les méthodes regroupées, classifications, limites et hypothèses de contenu avant le blocage.

Préparation, compatibilité et stabilité

bash

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

La préparation évalue la configuration de production ; la compatibilité affiche la matrice testée ; la stabilité décrit le contrat des surfaces publiques. Ces résultats ne remplacent pas les tests de rejeu ni la revue propre à l’application.

Règles, rejeu et simulation

bash

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

Conservez les fixtures de trafic valide et malveillant dans le contrôle de version. La promotion doit échouer si le trafic valide est bloqué ou si les cas malveillants ne correspondent plus aux contrôles attendus.

Politique CI

bash

npx dhal ci

policy.ci peut interdire les modes dangereux, exiger la signature des webhooks, contrôler les règles en surveillance et rejeter les suppressions expirées.

Rapport de support et contrôle de version

bash

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

Vérifiez les rapports avant de les partager. Ne publiez pas de secrets, identifiants, jetons ou trafic non expurgé.

Liste de contrôle d’application

Avant d’activer block ou strict, confirmez :

la version exacte est épinglée et le runtime pris en charge ;
schemaVersion vaut "1" ;
les changements d’intégration ou OpenAPI ont été revus ;
validation, migration, doctor et préparation réussissent ;
les fixtures valides et malveillantes réussissent ;
Redis ou Valkey est partagé entre les instances ;
signature, expurgation et fermeture via close() sont configurées ;
le retour à monitor est documenté et testé.