CLI (erp-preflight)

Die CLI ist das Paket @erppreflight/cli (Verzeichnis packages/cli): ein einzelnes Node.js-Skript ohne Abhängigkeiten, das die REST-API von ERP Preflight aufruft. Analysen laufen immer auf dem Server mit den deterministischen Engines; die CLI wertet nie selbst Regeln aus. Sie benötigt Node.js 18 oder neuer, weil sie das eingebaute fetch verwendet.

Das Paket ist nicht in der öffentlichen npm-Registry veröffentlicht. Aus einer Kopie des Paketverzeichnisses installieren Sie es global oder rufen das Skript direkt auf:

npm install -g ./packages/cli              # stellt erp-preflight und erp-preflight-mcp bereit
node packages/cli/bin/erp-preflight.js --help

Die CLI authentifiziert sich mit einem API-Schlüssel der Organisation, den sie als X-Api-Key sendet.

erp-preflight login --key erppf_live_… --api-url https://api.example.com
erp-preflight status

login prüft den Schlüssel, indem es die Projekte auflistet (der Schlüssel braucht projects:read), und speichert Schlüssel und URL in ~/.erppreflight/config.json — angelegt mit Dateimodus 0600 in einem Verzeichnis mit Modus 0700. status zeigt die Betriebsbereitschaft der API und ob ein Schlüssel konfiguriert ist.

• API-URL: --api-url, sonst ERP_PREFLIGHT_API_URL, sonst die von login gespeicherte URL, sonst http://localhost:3001. Fehlt /api/v1, wird es angehängt.
• API-Schlüssel: ERP_PREFLIGHT_API_KEY, sonst der von login gespeicherte Schlüssel. Setzen Sie in CI die Umgebungsvariable, statt login auszuführen.
• Konfigurationsverzeichnis: ERP_PREFLIGHT_CONFIG_DIR ersetzt ~/.erppreflight.

erp-preflight login --key <api_key> [--api-url <url>]
erp-preflight status
erp-preflight project list
erp-preflight project create --name <name> [--release S4H_2023] [--description <text>]
erp-preflight upload <projectId> <file> [file ...]
erp-preflight analyze <projectId> --engines <E1,E2> [--files <id,...>] [--release <release>] [--wait] [--timeout 600] [--fail-on <severities>]
erp-preflight analyze <alias> <path ...> --project <projectId> [--wait] [--timeout 600] [--fail-on <severities>]
erp-preflight findings <projectId> | --analysis <analysisId> [--severity <severity>] [--fail-on <severities>]
erp-preflight report export <projectId> <analysisId> [--format PDF] [--out <file>]
erp-preflight report download <analysisId> [--out <file>]
erp-preflight version

• project create benötigt den Scope projects:write, den in der Web-App angelegte Schlüssel nicht haben.
• upload schickt jede Datei durch die serverseitigen Upload-Prüfungen (Dateityp, Archivgrenzen, Malware-Scan, Schwärzung von Geheimnissen) und gibt Datei-ID, Status und Anzahl der Schwärzungen aus, mit --json zusätzlich den SHA-256 der lokalen Datei. Endet eine Datei nicht als CLEAN, schlägt der Befehl fehl.
• report export erzeugt einen Bericht — PDF (Standard), XLSX, CSV, JSON_BUNDLE oder HTML_OFFLINE —, speichert ihn unter --out oder dem vom Server gelieferten Dateinamen und gibt seinen SHA-256 aus.
• report download speichert das Reproduzierbarkeits-Bundle eines Laufs als ZIP-Datei.

Wie Sie Tools von ERP Preflight aus einem Coding-Agenten nutzen, steht unter MCP-Server.

analyze <projectId> startet die in --engines genannten Engines — Engine-Typen wie OPD_GUARD oder die Aliasse unten — auf den Dateien aus --files, andernfalls auf allen CLEAN-Artefakten des Projekts. Ohne --wait endet der Befehl, sobald der Lauf eingereiht ist, und gibt dessen ID aus.

Mit --wait fragt die CLI alle 2 Sekunden den Status ab, bis der Lauf COMPLETED, PARTIAL, FAILED oder CANCELLED ist, höchstens --timeout Sekunden lang (Standard 600). Danach gibt sie die Befunde aus — Schweregrad, Regel, Konfidenz, Titel und Fundstelle der Evidenz; die Tabelle zeigt die ersten 200 — und wendet --fail-on an (siehe CI-Integration).

analyze <alias> <path ...> --project <projectId> lädt lokale Dateien hoch und startet die passende Engine in einem Schritt. Aliasse: clean-core (CLEAN_CORE_OBJECT_GUARD), api-diff (API_CHANGE_GUARD), mfs (MFS_BLACKBOX), opd (OPD_GUARD), forms (FORM_DOCTOR) und transports (TRANSPORT_DEPENDENCY_ANALYZER). Verzeichnisse werden rekursiv durchsucht, ohne .git und node_modules, und zwar nach Dateien mit den Endungen .abap, .prog, .incl, .xml, .xsd, .json, .csv, .edmx, .wsdl oder .xdp — den analysierbaren Typen, die die Upload-Prüfung annimmt. Archive, PDFs und Textdateien werden nur hochgeladen, wenn Sie sie ausdrücklich angeben.

findings <projectId> listet die Befunde aller Läufe des Projekts einschließlich früherer Erkennungen, findings --analysis <analysisId> die eines einzelnen Laufs. --severity CRITICAL behält Befunde dieses und höherer Schweregrade.

• --json gibt maschinenlesbares JSON statt Tabellen aus. Bei analyze --wait enthält es die Lauf-ID (analysisId), Status, Engines, Anzahl der Dateien, eine Zusammenfassung nach Schweregrad und alle Befunde.
• --http-timeout <seconds> legt das Timeout jeder HTTP-Anfrage fest (Standard 60).
• Setzen Sie Optionen ohne Wert wie --wait und --json hinter die Positionsargumente: Folgt auf eine Option ein Wort, das nicht mit -- beginnt, gilt es als deren Wert.

Exit-Codes:

• 0 — Erfolg.
• 1 — Fehler: API- oder Netzwerkfehler, eine von den Upload-Prüfungen abgewiesene oder in Quarantäne gestellte Datei, keine CLEAN-Artefakte, ein mit FAILED oder CANCELLED beendeter Lauf oder ein Timeout von --wait.
• 2 — Aufruf oder Authentifizierung: fehlende Argumente, unbekannter Befehl, Datei nicht gefunden, kein API-Schlüssel konfiguriert oder HTTP 401/403 von der API (etwa ein fehlender Scope).
• 3 — Qualitätstor verletzt (--fail-on).