mage-remote-run mit JSON Body Support und anderen neuen Features

mage-remote-run mit JSON Body Support und anderen neuen Features
Magento

Zwei Releases an einem Tag - das passiert, wenn Features bereit sind. Am 17. Juni 2026 haben ich v1.9.0 und v1.10.0 von mage-remote-run veröffentlicht. Das Highlight in v1.9: Virtual Commands unterstützen jetzt JSON Request Bodies — POST- und PUT-Requests gegen die Magento REST API sind damit ohne eigenen JavaScript-Code möglich. v1.10 bringt eine sauberere Plugin-Infrastruktur: Inkompatible Plugins werden jetzt beim Laden erkannt und mit klarer Fehlermeldung abgewiesen.

v1.9.0: Virtual Commands mit JSON Body, Choices und interaktiven Prompts

Virtual Commands sind seit v1.4 ein zentrales Erweiterungs-Feature: REST-Requests per Konfiguration definieren, ohne JavaScript schreiben zu müssen. Bisher waren sie auf GET-Requests beschränkt. Das ist jetzt Geschichte.

JSON Body Templates

Mit body in der Command-Definition lassen sich POST- und PUT-Requests direkt aus der Konfiguration absetzen. Der Body ist ein JSON-Template. Optionen werden als Platzhalter eingebettet und zur Laufzeit ersetzt.

{
  "name": "customer update-email",
  "method": "PUT",
  "endpoint": "/V1/customers/:id",
  "description": "Update customer email address",
  "body": {
    "customer": {
      "id": ":id",
      "email": ":email"
    }
  },
  "options": {
    "id": {
      "type": "string",
      "required": true,
      "description": "Customer ID"
    },
    "email": {
      "type": "string",
      "required": true,
      "description": "New email address"
    }
  }
}

mage-remote-run customer update-email --id 42 --email new@example.com

Damit öffnet sich die gesamte Magento REST API für Virtual Commands und eben nicht nur lesende Operationen, sondern auch schreibende Workflows, ohne eigenen Plugin-Code.

Die vollständige Dokumentation dazu findet ihr unter: mage-remote-run.muench.dev/extensibility/virtual-commands

Choices für Options-Definitionen

Optionen können jetzt vordefinierte Auswahlwerte bekommen. Das macht Commands benutzerfreundlicher und verhindert ungültige Eingaben:

"options": {
  "status": {
    "type": "string",
    "required": true,
    "description": "Order status",
    "choices": ["pending", "processing", "complete", "canceled"]
  }
}

Im interaktiven Modus erscheinen die choices als Auswahlmenü. Per CLI werden ungültige Werte direkt zurückgewiesen.

Interaktive Prompts für fehlende Pflichtoptionen

Virtual Commands fragen fehlende Required Options jetzt interaktiv ab anstatt mit einer Fehlermeldung abzubrechen. Das Verhalten hängt vom Kontext ab: Im Terminal erscheint ein Prompt, in CI/CD-Pipelines wird der Fehler wie bisher ausgegeben. Soweit möglich werden Variablen die bereits von CI/CD Systemen wie Gitlab-CI oder Github Actions standardmäßig definiert wurden (wie CI=1), automatisch erkannt, sodass der interaktive Modus nicht die Pipeline blockieren kann.

Für Pipelines lässt sich der interaktive Modus aber auch explizit deaktivieren:

NON_INTERACTIVE=1 mage-remote-run my-command
# alternativ:
NONINTERACTIVE=1 mage-remote-run my-command

Beide Environment-Variablen werden als Alias akzeptiert an das Homebrew-Konvention-Feeling für Shell-Scripting.

Weitere Änderungen in v1.9

  • Performance: Config-I/O läuft jetzt vollständig asynchron (fs.promises statt synchronem fs) — spürbar bei häufigen Profil-Wechseln
  • Performance: findRegisteredPluginIndex nutzt Promise.all für parallele Prüfungen
  • Fix: Verschluckte Fehler in Catch-Blöcken wurden repariert — Fehler sind jetzt sichtbar statt still ignoriert
  • Refactoring: Duplicated Filter-Matching-Logik wurde in parseFilterOption extrahiert
  • Deps: axios, zod, inquirer und @modelcontextprotocol/sdk auf aktuelle Versionen gehoben

v1.10.0: Plugin-Kompatibilitätsprüfung über peerDependencies

Plugins deklarieren seit v1.6 eine peerDependency auf mage-remote-run. Ab v1.10 wird diese beim Laden tatsächlich ausgewertet.

Wenn ein Plugin eine Version von mage-remote-run voraussetzt, die nicht mit der installierten übereinstimmt, bricht das Laden mit einer klaren Fehlermeldung ab — statt mit unerklärlichem Laufzeitverhalten.

Das ist das übliche Prinzip: explizit schlechter als stumm falsch. Wer Plugins entwickelt oder nutzt, deklariert die peerDependency in der package.json des Plugins:

{
  "name": "my-mage-remote-run-plugin",
  "peerDependencies": {
    "mage-remote-run": ">=1.10.0"
  }
}

Die Prüfung läuft beim Plugin-Laden — noch bevor Commands registriert werden. Inkompatible Plugins werden übersprungen und der Fehler protokolliert.

Update

npm update -g mage-remote-run

Oder direkt auf die aktuelle Version:

npm install -g mage-remote-run@latest

Feedback und Bugreports wie immer via GitHub Issues. Wer Virtual Commands produktiv einsetzt oder Plugins entwickelt... ich freue mich über Erfahrungsberichte.

Comments