CPQ-BML VS Code Extension

Eine professionelle, funktionsreiche Visual Studio Code-Erweiterung für Oracle CPQ BigMachines Language (BML). Diese Erweiterung ist die ultimative Entwicklungsumgebung für CPQ-Profis und bietet IntelliSense, Syntaxhervorhebung, robuste Diagnose-/Linting-Funktionen, workspace-weite Formatierung, Remote-REST-Integration und MCP-gestützte KI-Unterstützung.

📖 Inhaltsverzeichnis

• Funktionen auf einen Blick

• Kernfunktionen

  • 1. Sprachunterstützung & IntelliSense

  • 2. Workspace-Formatierer & Beautifier

  • 3. BML-Linter & Echtzeit-Diagnose

  • 4. Better Comments & Dokumentations-Header

  • 5. Interaktives Einstellungs-Dashboard-WebView

  • 6. Remote-REST-Integration & Synchronisation

  • 7. Model Context Protocol (MCP)-Server für KI-Integration

  • 8. KI-Agenten-Skills-Integration (AgentSkills.io)

  • 9. BML-Farbthemen

• Befehlsreferenz

• Konfigurationseinstellungen

• Formatierer-Einstellungen (.bmlbeautifyrc)

• Projektstruktur

• Installation & Einrichtung

• Lokale Entwicklung

• Lizenz & Changelog

Related MCP server: Salesforce CLI MCP Server

✨ Funktionen auf einen Blick

• 🎨 BML-Farbthemen: Vier maßgeschneiderte Editor-Farbschemata mit umfassender semantischer Token-Färbung.

• 💡 IntelliSense: Kontextbezogene automatische Vervollständigung, Signaturhilfe und Parameter-Tooltips.

• 🔍 Linter & Diagnose: 70+ Echtzeitprüfungen auf Sicherheitsprobleme (SQL-Injection, hartkodierte Geheimnisse), garantiert auftretende Kompilier-/Laufzeitfehler (verifiziert anhand der offiziellen BML-Dokumentation von Oracle), veraltete APIs und logische Fehler.

• 📖 Offline-Hilfe-Viewer: Docusaurus-artig gerenderte Dokumentation (mit :::note/:::warning-Hinweisboxen) öffnet sich sofort aus jedem Hover-Tooltip – keine Internetverbindung erforderlich.

• 🛠 Workspace-weite Formatierung: Verzeichnisse oder gezielte Ordner rekursiv formatieren.

• ☁ REST-Integration: BML-Funktionen direkt auf entfernten CPQ-Instanzen synchronisieren, kompilieren, validieren, debuggen und deployen.

• 🤖 KI-Agenten-Konnektivität (MCP): Entwickeln oder debuggen per KI mit dem sicheren lokalen Model Context Protocol (MCP)-Server.

• 🧠 KI-Agenten-Skills (AgentSkills.io): Enthält 8 vorkompilierte semantische Skills, um fundiertes CPQ- und BML-Domänenwissen in KI-Assistenten wie Claude Code einzubringen.

• 📝 Better Comments: Deutlich unterscheidbare visuelle Gestaltung für Aufgaben, Tags, Direktiven und Funktions-Header.

🔍 Kernfunktionen

1. Sprachunterstützung & IntelliSense

• Umfangreiche Syntaxhervorhebung: Vollständige Grammatikunterstützung für BML-Methoden, Kontrollflussanweisungen (if, elif, else, for), Datenbankabfragen (bmql), Operatoren und Literale.

• Snippet-Bibliothek: Sofortige, kontextbezogene Code-Gerüste für Schleifenkonstrukte, gängige String-Operationen, JSON-Manipulationen und Systemfunktionen.

• Autovervollständigung & Tooltips: Signaturen, Rückgabetypen und Parameter-Checklisten werden während der Eingabe eingeblendet und entsprechen den Oracle-CPQ-Spezifikationen.

• Offline-Hilfe-Viewer: Jeder Hover-Tooltip für eine eingebaute Funktion enthält einen Link 📖 Offline-Hilfe lesen, der ein schnelles, eigenständiges Dokumentationsfenster öffnet – keine Internetverbindung erforderlich. Er rendert Docusaurus-artige :::note/:::tip/:::warning-Hinweisboxen als richtige farbige Boxen (nicht als rohen Markdown-Text), passend zum Design deines Editors, und verwendet über mehrere Öffnungen hinweg dasselbe Fenster, sodass wiederholte Suchvorgänge sofort erfolgen, anstatt jedes Mal eine Vorschau neu zu starten.

• Rechtschreibprüfungs-Integration: Vorkonfiguriert mit cspell.json-Definitionen, um CPQ-spezifische Funktionen (strtojavadate, jsonarrayrefid, bmql usw.) automatisch zu unterstützen, ohne Rechtschreibfehler auszulösen.

2. Workspace-Formatierer & Beautifier

• Rekursive Formatierung: Führe CPQ-BML: Beautify / Format All BML Files in Workspace (cpqBml.beautifyWorkspace) aus, um BML-Dateien rekursiv zu formatieren.

• Ordnerauswahl-UI: Ein Quick-Pick-Auswahldialog mit Mehrfachauswahl zeigt Workspace-Stammpfade und Ordner an, sodass du bestimmte Module gezielt ansteuern kannst.

• CPQ-Konventionen: Standardisiert Einrückung, Abstände, Klammer-Layouts und erzwingt Großschreibungsregeln, wie das automatische Ersetzen des Schlüsselworts not durch das vom Compiler geforderte NOT.

• Flexible Konfiguration: Das Verhalten des Formatierers kann für bestimmte Verzeichnisse mithilfe lokaler .bmlbeautifyrc-JSON-Dateien überschrieben werden.

3. BML-Linter & Echtzeit-Diagnose

Die Erweiterung enthält einen eigenen BML-nativen statischen Analyzer, um Fehler, Anti-Patterns und Schwachstellen zu erkennen, bevor du auf CPQ hochlädst:

4. Better Comments & Dokumentations-Header

Inline-Unterdrückungen

Sie können bestimmte Linter-Regeln granular mithilfe von Kommentaren umgehen. Direktiven sind case-insensitive und funktionieren sowohl in Zeilenkommentaren als auch in Blockkommentaren:

// bml-lint-disable-file               ← suppress everything in this file
// bml-lint-disable                    ← start of suppressed block
// bml-lint-enable                     ← end of suppressed block
x = 10 / 0; // bml-lint-disable-line  ← suppress diagnostics on this line
/* bml-lint-disable-next-line */       ← suppress all diagnostics on the next line
// bml-lint-disable-next-line bml-operator-fix, bml-spelling-error
x = 10 / 0;                            ← only those two codes are suppressed

Unterstützte Direktiven-Stile:

[!TIP] Das Weglassen einer Codeliste unterdrückt alle Diagnosen; die Auflistung eines oder mehrerer bml-*-Codes unterdrückt nur diese spezifischen Regeln. Glühbirnen-Schnellkorrekturen (Ctrl+. oder Cmd+.) sind für viele Diagnosen verfügbar und ermöglichen es Ihnen, Semikolon-Stil, Variablentippfehler, Formatierungsfehler oder veraltete APIs sofort automatisch zu beheben.

4. Bessere Kommentare & Dokumentations-Header

Verbessern Sie die Lesbarkeit des Codes, indem Sie Kommentare in kategorisierte Aufgaben, Status oder visuelle Hervorhebungen umwandeln.

Benutzerdefinierte Tag-Formatierung

Direktiven & Block-Header

• Lint- & Formatierungs-Direktiven: Kommentare wie // bml-lint-disable-line oder /* beautify ignore:start */ werden mit einer markanten violetten Umrandung gestaltet, um Steuer-Tags sichtbar, aber dezent zu halten.

• Standard-Dokumentations-Header: Funktions-Doc-Blöcke, die mit Function Name:, Description:, Inputs: oder Returns: beginnen, werden automatisch gruppiert und in hellblauen kursiven Schriftarten eingefärbt.

5. Interaktives Einstellungs-Dashboard WebView

Konfigurieren Sie Verbindungen und Funktionen über ein benutzerdefiniertes grafisches Dashboard mit CPQ-BML: Open Settings (cpqBml.settings.open):

• Verbindungs-Tab: Geben Sie die Site-URL Ihres Servers, das Authentifizierungsschema und aktive API-Anmeldeinformationen ein.

• Umgebungs-Tab: Speichern Sie mehrere Sandboxes (z. B. Dev, Test, UAT, Production), um aktive Ziele zu wechseln.

• Funktionen-Tab: Schalten Sie Linting-Regeln, Better-Comments-Formatierung und allgemeine Erweiterungsassistenten in einer übersichtlichen Benutzeroberfläche um.

• Sichere Speicherintegration: Verbindet sich direkt mit der VS Code Secret Storage API. Anmeldeinformationen, Passwörter und Token werden im Schlüsselbund Ihres Betriebssystems gespeichert und niemals in Klartext-Konfigurationsdateien geschrieben.

• Verbindung testen: Ein Ein-Klick-Check überprüft die Remote-Anmeldeinformationen und die Site-Konnektivität unmittelbar vor dem Anwenden der Einstellungen.

6. Remote-REST-Integration & Synchronisierung

Führen Sie CPQ-Entwicklungsworkflows vollständig in Ihrem lokalen Editor aus:

• Code abrufen: Rufen Sie Utility-Library-Funktionen und Commerce-Process-Funktionen (cpqBml.rest.pullLibraryFunctions, cpqBml.rest.pullCommerceFunctions) zusammen mit ihren Metadaten vom Remote-Server ab.

• Remote-Validierung & Kompilierung: Führen Sie CPQ-BML: Validate Current File Against CPQ aus, um den serverseitigen Compiler von Oracle für das aktive Dokument auszulösen und Syntaxdiagnosen lokal anzuzeigen.

• Sandbox-Debugger: Drücken Sie CPQ-BML: Debug Current Function on CPQ, um einen Parameterauswahl-Dialog zu starten, Testwerte an die Sandbox-Laufzeit zu senden und Standardausgaben im Terminal zu überprüfen.

• Bereitstellungssteuerung: Stellen Sie geänderten Code sofort bereit, entweder durch einzelne Dateispeicherungen, Batch-Bereitstellungen der Utility-Library oder vollständige Commerce-Process-Konfigurationen.

7. Model Context Protocol (MCP)-Server für KI-Integration

Die Erweiterung führt einen integrierten, sicheren Model Context Protocol (MCP)-Server aus, der KI-Codierungsassistenten (wie Claude Code) ermöglicht, Code in Ihrem Arbeitsbereich sicher zu inspizieren, zu debuggen und bereitzustellen.

graph TD
    subgraph External Environment
        AI[AI Client / Claude Code]
    end
    subgraph VS Code Host
        MCP[MCP Server <br> 127.0.0.1:47821]
        Ext[CPQ-BML Extension]
        Sec[OS Keychain / Secret Storage]
    end
    subgraph Cloud Service
        CPQ[Oracle CPQ Sandbox / Instance]
    end

    AI -- "MCP JSON-RPC Protocol" --> MCP
    MCP -- "Internal Bridge (No Auth Shared)" --> Ext
    Ext -- "Retrieves Credentials" --> Sec
    Ext -- "REST API Requests" --> CPQ

Sicherheitsmodell

Anmeldeinformationen, Cookies und geheime Token werden im sicheren Kontext der Erweiterung aufbewahrt. Der MCP-Server legt diese Werte gegenüber dem KI-Client nicht offen. Er fungiert nur als Ausführer und leitet Anfragen über die lokale Erweiterungsinstanz weiter.

KI-Arbeitsisolierung

Wenn ein KI-Agent über MCP eine Dateiänderung oder einen Download anfordert, erstellt die Erweiterung eine isolierte Arbeitskopie [variableName]-AI.bml. Dies verhindert, dass der Agent Ihre lokalen Skripte überschreibt, und stellt sicher, dass Sie Änderungen vor dem Übernehmen mit einem Diff-Tool überprüfen können.

Verfügbare MCP-Tools

• list_util_functions: Alle Remote-Utility-Library-Funktionen auflisten.

• list_commerce_functions: Alle Commerce-Skripte auf der CPQ-Instanz auflisten.

• pull_function: Standard-BML abrufen und lokal als .bml- und -meta.json-Dateien speichern.

• save_function: Aktualisierungen auf die CPQ-Umgebung anwenden.

• validate_function: Den CPQ-Servercompiler abfragen, um Änderungen zu validieren.

• debug_function: Die Funktion remote mit Testparametern ausführen.

• deploy_function / mass_deploy_util_functions: Einzelne oder gebündelte Funktionen bereitstellen.

• deploy_commerce_process: Die gesamte Prozesskonfiguration veröffentlichen.

• create_util_function: Eine brandneue Utility-Funktion erstellen und veröffentlichen.

• create_override: Eine bearbeitbare Überschreibung einer Standard- (System-) Funktion erstellen – erforderlich, bevor sie validiert, gespeichert oder bereitgestellt werden kann.

• remove_override: Eine überschriebene Standardfunktion auf die Systemversion von CPQ zurücksetzen (zerstörerisch; erfordert confirm:true).

8. KI-Agenten-Fähigkeiten-Integration (AgentSkills.io)

CPQ-BML wird mit einem vorkompilierten Satz von „Agent Skills" geliefert, der um die AgentSkills.io-Spezifikation herum entwickelt wurde. Dies injiziert tiefes Domänenwissen in KI-Codierungsassistenten (wie Claude Code oder Cursor), die diese Fähigkeiten nativ parsen, wenn sie mit Ihrem Arbeitsbereich interagieren.

Null-Konfiguration-Setup: Wenn Sie den MCP-Server in den Erweiterungseinstellungen aktivieren, registriert CPQ-BML diese Fähigkeiten automatisch in Ihrem Arbeitsbereich. Es gibt keinen manuellen Setup-Befehl, den Sie ausführen müssen!

Um das Erweiterungspaket klein und Ihren Arbeitsbereich sauber zu halten:

• Die umfangreiche semantische Wissensbasis wird zur Build-Zeit in ein hochoptimiertes .br-Archiv komprimiert.

• Zur Laufzeit dekomprimiert die Erweiterung dieses Wissen transparent in Ihr sicheres VS Code Global Storage-Verzeichnis.

• Sie stellt automatisch Zeigerdateien (z. B. .agents/skills.json, CLAUDE.md, .cursorrules) in Ihrem Arbeitsbereich bereit, die Ihren KI-Assistenten zum globalen Speicherort führen.

Anstatt dass Ihre KI blind versucht, BML mit standardmäßigen JavaScript-Annahmen zu bearbeiten, bietet die Erweiterung kontextbezogene Direktiven zu:

• BMLs einzigartige Syntaxeinschränkungen (z. B. kein var oder let, == statt ===, NOT anstelle von !).

• Direkter Datenbankzugriff vs. BMQL-Syntax.

• Best Practices für Wörterbuch-, JSON- und String-Manipulation in CPQ.

• Wie Sie die CPQ-BML-MCP-Tools (wie pull_function, save_function, validate_function) korrekt als Teil eines End-to-End-KI-Entwicklungsworkflows nutzen.

Die KI ruft diese kontextuellen Regeln in Echtzeit dynamisch ab und überbrückt so die Lücke zwischen standardmäßiger LLM-Codegenerierung und der proprietären Laufzeit von Oracle CPQ.

9. BML-Farbschemata

Vier spezialisierte Farbschemata sind in der Erweiterung enthalten:

• BML Dark

• BML Dark Default

• BML Light

• BML Light Default

[!NOTE] Syntaxfärbung ist themengetrieben. Die Erweiterung erzwingt keine Überschreibungen für externe Designs. Wählen Sie eines der BML-Designs (Ctrl+K Ctrl+T / Cmd+K Cmd+T), um CPQ-spezifische Token-Farben anzuzeigen.

Farbdetails

• Kategorisierte Funktionen: Verschiedene Farben werden den integrierten Funktionskategorien zugewiesen (z. B. String, Mathe, Datum, DB/BMQL, Array, URL, Wörterbuch, JSON, XML).

• Attributzugriff: CPQ-Membervariablen (wie line.attribute und transaction.attribute) werden anders hervorgehoben als allgemeine Variablen.

• Operatoren: Mathematische, logische und Zuweisungsoperatoren werden unterschiedlich gestaltet, sodass Sie Syntaxfehler wie = anstelle von == erkennen können.

⌨ Befehlsreferenz

Verwenden Sie die Befehlspalette (Ctrl+Shift+P / Cmd+Shift+P), um diese Aktionen auszulösen:

⚙ Konfigurationseinstellungen

Konfigurieren Sie diese Optionen in der settings.json von VS Code oder über die Benutzeroberfläche des Einstellungs-Editors:

{
  "cpqBml.connection.enabled": true,
  "cpqBml.connection.siteUrl": "example.bigmachines.com",
  "cpqBml.connection.authMethod": "basic",
  "cpqBml.connection.username": "api_developer",
  "cpqBml.connection.environments": [
    {
      "name": "Dev Sandbox",
      "siteUrl": "dev.bigmachines.com",
      "username": "api_developer",
      "authMethod": "basic"
    }
  ],
  "cpqBml.rest.restVersion": "v18",
  "cpqBml.rest.commerceProcess": "oraclecpqo",
  "cpqBml.rest.commerceDocument": "transaction",
  "cpqBml.rest.pullFolder": "library",
  "cpqBml.features.lint": true,
  "cpqBml.features.comments": true,
  "cpqBml.mcp.enable": false,
  "cpqBml.mcp.port": 47821,
  "cpqBml.mcp.logToTerminal": false,
  "cpqBml.debug.logRestDetails": false,
  "cpqBml.debug.logOutputToFile": false
}

🔧 Formatierungseinstellungen (.bmlbeautifyrc)

Platzieren Sie eine .bmlbeautifyrc-Konfigurationsdatei in einem beliebigen Verzeichnis, um die BML-Formatierungsregeln anzupassen. Die Optionen sind an JS-beautify-Strukturen angelehnt:

{
  "indent_size": 2,
  "brace_style": "collapse",
  "preserve_newlines": true,
  "max_preserve_newlines": 1,
  "space_before_conditional": true
}

📂 Projektstruktur

Das Projekt hat eine modulare Designstruktur mit klarer Trennung von BML-Editor-Diensten, REST-Netzwerk, Testwerkzeugen und KI-Integration:

├── app/                              # Extension Core Source Code
│   └── lang/                         # Language Intelligence & Tooling
│       ├── beautify/                 # Code Formatter & Beautification Engine
│       │   ├── commandWorkspace.js   # Workspace-wide mass formatter
│       │   ├── docHeader.js          # Auto-insert /// doc block comment completion
│       │   └── index.js              # Formatting core config/integration
│       ├── comments/                 # Better Comments parser (tags, directives, headers)
│       ├── intellisense/             # IntelliSense (autocompletions, hovers, signatures)
│       │   ├── index.js              # Go to definition, References, Rename registrations
│       │   ├── workspaceIndex.js     # Codebase scanner indexing util.* & commerce.*
│       │   ├── helpViewer.js         # Fast offline docs webview (Docusaurus-style ::: admonitions)
│       │   └── custom-snippets.json  # Smart snippet database
│       ├── lint/                     # Real-time Native Static Diagnostics
│       │   ├── lint.js               # Central rule runner pipeline
│       │   ├── nullSafety.js         # Checks nullable results of bmql() / get()
│       │   ├── infiniteLoop.js       # Identifies empty or non-populating loops
│       │   └── best-practices/       # BMQL safety, security, doc-verified guaranteed failures, etc.
│       ├── mcp/                      # Model Context Protocol AI Tool Integration
│       │   ├── server.js             # Local MCP server implementation
│       │   └── tools/                # Declarative AI helper tools
│       ├── metrics/                  # Code quality analysis WebView Dashboard
│       │   ├── complexity.js         # Cyclomatic complexity & nesting depth calculations
│       │   ├── report.js             # Metrics accumulator logic
│       │   └── reportWebview.js      # WebView layout rendering
│       ├── rest/                     # Oracle CPQ REST Client Integration
│       ├── settings-panel/           # Extension settings GUI dashboard WebView
│       ├── testing/                  # Safe sandboxed local execution & unit testing
│       │   ├── runner.js             # Sidecar *.bmltest.json executor
│       │   └── snapshot.js           # Regression snapshot comparisons
│       └── xslt/                     # XSLT formatting, & linking features
│
├── test/                             # Automated Test Suites
│   ├── linter/                       # Tests for suppressions & core linter behaviors
│   ├── mcp/                          # Tests for local MCP tool server
│   └── rest/                         # Offline mocked testing for CPQ REST sync
│
├── extension.js                      # Extension Activation/Deactivation Entry-point
├── package.json                      # VS Code Extension manifest & command declarations
└── README.md                         # Project documentation

🚀 Installation und Einrichtung

1. Aus dem Marketplace installieren: Suchen Sie im VS Code-Erweiterungsbereich (Ctrl+Shift+X / Cmd+Shift+X) nach "CPQ-BML" und klicken Sie auf Installieren.

2. Erstmaliges Onboarding: Beim ersten Laden wird das Einstellungs-Dashboard automatisch gestartet.

3. Umgebungen einrichten: Geben Sie Ihre Site-Details ein, wählen Sie Ihre Authentifizierungsmethode und überprüfen Sie die Verbindung.

4. Anmeldedaten sichern: Verwenden Sie die Befehle CPQ-BML: Set CPQ Password oder CPQ-BML: Set CPQ Auth Token, um Ihre Passwörter oder Schlüssel sicher zu speichern.

💻 Lokale Entwicklung

Wenn Sie diese Erweiterung ausführen, anpassen oder dazu beitragen möchten:

Voraussetzungen

• Node.js (v22 oder neuer empfohlen)

• Visual Studio Code

Schritte

1. Repository klonen:

   git clone https://github.com/vikram-vn/cpq-bml.git
   cd cpq-bml

2. Abhängigkeiten installieren:

   npm install

3. Projekt kompilieren:

   npm run compile

4. Erweiterungshost ausführen: Öffnen Sie den Stammarbeitsbereich in VS Code und drücken Sie F5 (oder navigieren Sie zu Run and Debug -> Launch Extension). Dadurch wird ein Fenster für den Erweiterungsentwicklungshost geöffnet, in dem Sie die BML-Unterstützung sofort testen können.

📄 Lizenz & Änderungsprotokoll

• Lizenz: Dieses Projekt ist unter der MIT-Lizenz lizenziert.

• Änderungsprotokoll: Detaillierte Versionshistorie, Ergänzungen und Aktualisierungen finden Sie in CHANGELOG.md.

• Haftungsausschluss: Diese Erweiterung ist ein unabhängiges Community-Projekt und ist weder mit der Oracle Corporation noch mit BigMachines verbunden, wird von diesen nicht gesponsert, unterstützt oder anderweitig assoziiert.