CLI und Produktionsbereitschaft — dhal-Dokumentation

dhal-Dokumentation

Seite 8 von 9

Die dhal-CLI ist in @rokadhq/dhal enthalten und wird mit npx dhal ausgeführt.

Zentrale Befehle

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

Geführte Projekteinrichtung

bash

npx dhal add

dhal add erkennt Express, Fastify, NestJS, Koa oder Hono aus package.json sowie npm, pnpm, Yarn oder Bun aus der Sperrdatei. Der Standardaufruf ist schreibgeschützt: Er zeigt ein Framework-Preset, eine dhal.json im Überwachungsmodus, ein Integrationsmodul, den Installationsbefehl und genaue Registrierungsschritte.

Nach der Prüfung:

bash

npx dhal add --write

Wichtige Optionen:

text

--framework <name>       Erkennung überschreiben
--config <pfad>          Pfad der Konfiguration
--integration <pfad>     Pfad des erzeugten Integrationsmoduls
--write                  Vorgeschlagene Dateien erstellen
--force                  Vorhandene erzeugte Ausgaben überschreiben

Der Befehl verändert vorhandenen Anwendungscode niemals automatisch.

Initialisieren, validieren und migrieren

bash

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

init erstellt eine allgemeine Monitor-first-Konfiguration. test-config validiert die effektive Konfiguration. migrate --check meldet notwendige Migrationen, ohne Dateien zu ändern. Verwenden Sie migrate --write erst nach der Prüfung.

Doctor und vorsichtige Reparatur

bash

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

doctor --fix hat absichtlich einen engen Umfang. Es kann eine fehlende Monitor-Konfiguration erstellen, eine kompatible Konfiguration vor schemaVersion migrieren und vor Änderungen dhal.json.bak anlegen.

Blockierung, Proxy-Vertrauen, Redis, Reputation, OpenTelemetry oder Webhooks werden nicht automatisch aktiviert. Nutzen Sie --dry-run für eine Vorschau und --no-backup nur bei vorhandener externer Sicherung.

Framework-Presets

bash

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

Version 1.1 ergänzt:

text

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

Die bestehenden Presets starter, api-production, auth-hardened, strict-json-api, behind-proxy und observability bleiben verfügbar. Prüfen und validieren Sie jede erzeugte Ausgabe.

OpenAPI-Inspektion

bash

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

JSON wird strukturell analysiert. YAML verwendet einen vorsichtigen Scanner für übliche Pfade, Methoden, Tags, Sicherheitsangaben und Inhaltstypen. Komplexes YAML mit Ankern, Merge-Schlüsseln oder externen Referenzen sollte zuerst in JSON umgewandelt werden.

Die Inspektion klassifiziert Authentifizierung, Multipart-Uploads, Webhooks, teure Operationen, explizit öffentliche Operationen und JSON-Anfragekörper.

Monitor-Policies aus OpenAPI erzeugen

bash

npx dhal openapi generate openapi.yaml

Parameter werden in Dhal-Platzhalter umgewandelt:

text

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

Alle erzeugten Routen bleiben im Modus monitor. Bestehende Routenprofile werden bewahrt und als preserve-existing gemeldet.

bash

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

Die erste Form erstellt eine Sicherung. Mit --force ersetzen Sie eine vorhandene separate Ausgabe, mit --no-backup unterdrücken Sie die Sicherung und mit --default-max ändern Sie das erzeugte Standardlimit.

Die erzeugte Policy ist ein Sicherheitsvorschlag, kein Autorisierungsmodell. Prüfen Sie gruppierte Methoden, Klassifikationen, Grenzen und Inhaltstypannahmen vor der Durchsetzung.

Readiness, Kompatibilität und Stabilität

bash

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

Readiness bewertet die Produktionskonfiguration, Kompatibilität zeigt die getestete Matrix und Stabilität den Vertrag öffentlicher API-Flächen. Diese Ergebnisse ersetzen weder Replay-Tests noch anwendungsspezifische Prüfung.

Regeln, Replay und Simulation

bash

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

Speichern Sie Fixtures für gültigen und schädlichen Datenverkehr in der Versionsverwaltung. Eine Promotion muss fehlschlagen, wenn gültiger Verkehr unerwartet blockiert wird oder schädliche Fälle nicht mehr zur erwarteten Kontrolle passen.

CI-Policy

bash

npx dhal ci

policy.ci kann unsichere Modi verbieten, Webhook-Signierung verlangen, Monitor-Regeln prüfen und abgelaufene Ausnahmen ablehnen.

Supportbericht und Release-Prüfung

bash

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

Prüfen Sie Berichte vor dem Teilen. Veröffentlichen Sie keine Geheimnisse, Zugangsdaten, Token oder unmaskierten Produktionsverkehr.

Checkliste vor der Durchsetzung

Vor block oder strict prüfen Sie:

exakte Version ist festgelegt und Laufzeit unterstützt;
schemaVersion ist "1";
Einrichtungs- oder OpenAPI-Änderungen wurden geprüft;
Validierung, Migration, Doctor und Readiness sind erfolgreich;
gültige und schädliche Replay-Fixtures bestehen;
Redis oder Valkey wird zwischen Instanzen geteilt;
Signierung, Maskierung und Shutdown über close() sind konfiguriert;
Rückkehr zu monitor ist dokumentiert und getestet.