Extensión CPQ-BML para VS Code

Una extensión profesional y repleta de funciones de Visual Studio Code para Oracle CPQ BigMachines Language (BML). Esta extensión sirve como el entorno de desarrollo definitivo para los profesionales de CPQ, ya que ofrece IntelliSense, resaltado de sintaxis, diagnóstico/linting robusto, formato en todo el espacio de trabajo, integración REST remota y asistencia de IA impulsada por MCP.

📖 Tabla de contenido

• Características de un vistazo

• Capacidades clave

  • 1. Compatibilidad con el lenguaje e IntelliSense

  • 2. Formateador y embellecedor del espacio de trabajo

  • 3. Linter BML y diagnóstico en tiempo real

  • 4. Better Comments y encabezados de documentación

  • 5. Panel de configuración interactivo WebView

  • 6. Integración REST remota y sincronización

  • 7. Servidor Model Context Protocol (MCP) para integración con IA

  • 8. Integración de habilidades de agentes de IA (AgentSkills.io)

  • 9. Temas de color BML

• Referencia de comandos

• Ajustes de configuración

• Ajustes del formateador (.bmlbeautifyrc)

• Estructura del proyecto

• Instalación y configuración

• Desarrollo local

• Licencia y registro de cambios

Related MCP server: Salesforce CLI MCP Server

✨ Características de un vistazo

• 🎨 Temas de color BML: Cuatro temas de editor adaptados que ofrecen un profundo coloreado de tokens semánticos.

• 💡 IntelliSense: Autocompletado sensible al contexto, ayuda de firmas e información sobre parámetros.

• 🔍 Linter y diagnóstico: Más de 70 comprobaciones en tiempo real de seguridad (inyección SQL, secretos codificados), fallos garantizados de compilación/ejecución verificados con la documentación BML oficial de Oracle, API obsoletas y errores lógicos.

• 📖 Visor de ayuda sin conexión: Documentación renderizada al estilo Docusaurus (con llamadas :::note/:::warning) que se abre al instante desde cualquier información emergente: no se requiere conexión a internet.

• 🛠 Formato en todo el espacio de trabajo: Embellece recursivamente directorios o carpetas concretas.

• ☁ Integración REST: Sincroniza, compila, valida, depura e implementa funciones BML directamente en instancias CPQ remotas.

• 🤖 Conectividad con agentes de IA (MCP): Crea o depura mediante IA usando el servidor local seguro del Model Context Protocol (MCP).

• 🧠 Habilidades de agentes de IA (AgentSkills.io): Incluye 8 habilidades semánticas precompiladas para inyectar un profundo conocimiento del dominio CPQ y BML en asistentes de IA como Claude Code.

• 📝 Better Comments: Estilo visual diferenciado para tareas, etiquetas, directivas y encabezados de funciones.

🔍 Capacidades clave

1. Compatibilidad con el lenguaje e IntelliSense

• Resaltado de sintaxis enriquecido: Compatibilidad gramatical completa con métodos BML, sentencias de control de flujo (if, elif, else, for), consultas de base de datos (bmql), operadores y literales.

• Biblioteca de fragmentos (snippets): Esqueletos de código instantáneos y sensibles al contexto para construcciones de bucles, operaciones comunes con cadenas, manipulaciones JSON y funciones del sistema.

• Autocompletado e información emergente: Las firmas, los tipos de retorno y las listas de parámetros se completan mientras escribes, de acuerdo con las especificaciones de Oracle CPQ.

• Visor de ayuda sin conexión: Cada información emergente de una función integrada incluye un enlace 📖 Leer ayuda sin conexión que abre un panel de documentación rápido y autónomo: no se necesita conexión a internet. Representa las llamadas :::note/:::tip/:::warning al estilo Docusaurus como cuadros de colores adecuados (no como texto Markdown sin procesar), combinados con el tema de tu editor, y reutiliza un único panel en todas las aperturas para que las consultas repetidas sean instantáneas en lugar de relanzar una vista previa cada vez.

• Integración con corrector ortográfico: Preconfigurado con definiciones de cspell.json para admitir automáticamente funciones específicas de CPQ (strtojavadate, jsonarrayrefid, bmql, etc.) sin provocar errores ortográficos.

2. Formateador y embellecedor del espacio de trabajo

• Formato recursivo: Ejecuta CPQ-BML: Beautify / Format All BML Files in Workspace (cpqBml.beautifyWorkspace) para formatear recursivamente los archivos BML.

• Interfaz de selección de carpetas: Un selector quick-pick de selección múltiple muestra las rutas raíz y las carpetas del espacio de trabajo, lo que te permite seleccionar módulos específicos.

• Convenciones CPQ: Estandariza la sangría, los espacios, la disposición de llaves y aplica reglas de mayúsculas como reemplazar automáticamente la palabra clave not por NOT, tal como exige el compilador.

• Configuración flexible: El comportamiento del formateador se puede anular para directorios específicos mediante archivos JSON .bmlbeautifyrc locales.

3. Linter BML y diagnóstico en tiempo real

La extensión incluye un analizador estático nativo de BML personalizado para detectar defectos, antipatrones y vulnerabilidades antes de que subas el código a CPQ:

Supresiones en línea

Puedes omitir reglas específicas del linter de forma granular mediante comentarios. Las directivas no distinguen entre mayúsculas y minúsculas y funcionan tanto en comentarios de línea como en comentarios de bloque:

// 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

Estilos de directiva admitidos:

[!TIP] Omitir una lista de códigos suprime todos los diagnósticos; enumerar uno o más códigos bml-* suprime solo esas reglas específicas. Las Correcciones rápidas de la bombilla (Ctrl+. o Cmd+.) están disponibles para muchos diagnósticos, lo que te permite resolver automáticamente el estilo de los puntos y comas, errores tipográficos en variables, errores de formato o API obsoletas al instante.

4. Mejores comentarios y encabezados de documentación

Mejora la legibilidad del código estilizando los comentarios en tareas categorizadas, estados o llamadas visuales.

Estilo personalizado de etiquetas

Directivas y encabezados de bloque

• Directivas de lint y formato: Los comentarios como // bml-lint-disable-line o /* beautify ignore:start */ se estilizan con un borde púrpura distintivo para mantener las etiquetas de control visibles pero fuera del camino.

• Encabezados de documentación estándar: Los bloques de documentación de funciones que comienzan con Function Name:, Description:, Inputs: o Returns: se agrupan y colorean automáticamente con fuentes azul claro en cursiva.

5. Panel de configuración interactivo WebView

Configura conexiones y funciones mediante un panel gráfico personalizado usando CPQ-BML: Open Settings (cpqBml.settings.open):

• Pestaña de conexión: Introduce la URL del sitio de tu servidor, el esquema de autenticación y las credenciales activas de la API.

• Pestaña de entornos: Almacena varios sandboxes (p. ej., Dev, Test, UAT, Production) para cambiar entre destinos activos.

• Pestaña de funciones: Activa o desactiva reglas de lint, el estilo de Better Comments y los asistentes generales de la extensión en una interfaz limpia.

• Integración de almacenamiento seguro: Se conecta directamente con la API de Almacenamiento de Secretos de VS Code. Las credenciales, contraseñas y tokens se guardan en el llavero de tu sistema operativo, nunca se escriben en archivos de configuración en texto plano.

• Probar conexión: Una comprobación con un clic verifica las credenciales remotas y la conectividad del sitio inmediatamente antes de aplicar la configuración.

6. Integración y sincronización REST remota

Realiza flujos de trabajo de desarrollo de CPQ completamente dentro de tu editor local:

• Extraer código: Obtén funciones de la Biblioteca de utilidades y funciones de Procesos comerciales (cpqBml.rest.pullLibraryFunctions, cpqBml.rest.pullCommerceFunctions) del servidor remoto junto con sus metadatos.

• Validación y compilación remota: Ejecuta CPQ-BML: Validate Current File Against CPQ para activar el compilador del lado del servidor de Oracle en el documento activo y mostrar los diagnósticos de sintaxis localmente.

• Depurador de sandbox: Pulsa CPQ-BML: Debug Current Function on CPQ para abrir un diálogo de selección de parámetros, enviar valores de prueba al entorno de ejecución del sandbox y revisar las salidas estándar en la terminal.

• Controles de implementación: Implementa código modificado al instante mediante guardados de archivos individuales, implementaciones por lotes de la biblioteca de utilidades o configuraciones completas de procesos comerciales.

7. Servidor Model Context Protocol (MCP) para integración con IA

La extensión ejecuta un servidor Model Context Protocol (MCP) integrado y seguro, que permite a los asistentes de codificación con IA (como Claude Code) inspeccionar, depurar e implementar código de forma segura en tu espacio de trabajo.

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

Modelo de seguridad

Las credenciales, cookies y tokens secretos se mantienen dentro del contexto seguro de la extensión. El servidor MCP no expone estos valores al cliente de IA. Solo actúa como ejecutor, enrutando las solicitudes a través de la instancia local de la extensión.

Aislamiento del trabajo de IA

Cuando un agente de IA solicita una modificación o descarga de archivo a través de MCP, la extensión crea una copia de trabajo aislada [variableName]-AI.bml. Esto evita que el agente sobrescriba tus scripts locales y garantiza que puedas revisar los cambios mediante una herramienta de diferencias antes de confirmarlos.

Herramientas MCP expuestas

• list_util_functions: Enumera todas las funciones remotas de la biblioteca de utilidades.

• list_commerce_functions: Enumera todos los scripts comerciales en la instancia de CPQ.

• pull_function: Obtiene BML estándar y lo guarda localmente como archivos .bml y -meta.json.

• save_function: Aplica actualizaciones al entorno de CPQ.

• validate_function: Consulta el compilador del servidor de CPQ para validar los cambios.

• debug_function: Ejecuta la función de forma remota con parámetros de prueba.

• deploy_function / mass_deploy_util_functions: Implementa funciones individuales o por lotes.

• deploy_commerce_process: Publica la configuración completa del proceso.

• create_util_function: Crea y publica una función de utilidad completamente nueva.

• create_override: Crea una anulación editable de una función estándar (del sistema); es necesaria antes de que pueda validarse, guardarse o implementarse.

• remove_override: Revierte una función estándar anulada a la versión del sistema de CPQ (destructivo; requiere confirm:true).

8. Integración de habilidades de agentes de IA (AgentSkills.io)

CPQ-BML incluye un conjunto precompilado de «Agent Skills» (habilidades de agente) diseñado según la especificación de AgentSkills.io. Esto inyecta conocimiento profundo del dominio en los asistentes de codificación con IA (como Claude Code o Cursor) que analizan estas habilidades de forma nativa al interactuar con tu espacio de trabajo.

Configuración sin configuración previa: Cuando habilitas el servidor MCP en la configuración de la extensión, CPQ-BML registra automáticamente estas habilidades en tu espacio de trabajo. ¡No hay ningún comando de configuración manual que ejecutar! Para mantener el paquete de la extensión pequeño y tu espacio de trabajo limpio:

• La enorme base de conocimiento semántico se comprime en un archivo .br altamente optimizado en el momento de la compilación.

• En tiempo de ejecución, la extensión descomprime este conocimiento de forma transparente en tu directorio seguro de Almacenamiento Global de VS Code.

• Aprovisiona automáticamente archivos de puntero (p. ej., .agents/skills.json, CLAUDE.md, .cursorrules) en tu espacio de trabajo que dirigen a tu asistente de IA a la ubicación de almacenamiento global.

En lugar de que tu IA intente editar BML a ciegas usando suposiciones estándar de Javascript, la extensión proporciona directivas conscientes del contexto sobre:

• Las limitaciones de sintaxis únicas de BML (p. ej., sin var ni let, == en lugar de ===, NOT en lugar de !).

• Acceso directo a la base de datos frente a sintaxis BMQL.

• Prácticas recomendadas sobre manipulación de diccionarios, JSON y cadenas en CPQ.

• Cómo utilizar correctamente las herramientas MCP de CPQ-BML (como pull_function, save_function, validate_function) como parte de un flujo de trabajo de desarrollo de IA de extremo a extremo.

La IA obtiene dinámicamente estas reglas contextuales en tiempo real, cerrando la brecha entre la generación de código estándar de los LLM y el tiempo de ejecución propietario de Oracle CPQ.

9. Temas de color BML

Cuatro temas especializados se incluyen con la extensión:

• BML Dark

• BML Dark Default

• BML Light

• BML Light Default

[!NOTE] El coloreado de sintaxis está impulsado por el tema. La extensión no impone anulaciones sobre temas externos. Selecciona uno de los temas BML (Ctrl+K Ctrl+T / Cmd+K Cmd+T) para ver los colores de tokens específicos de CPQ.

Detalles de color

• Funciones categorizadas: Se asignan colores distintos a las categorías de funciones integradas (p. ej., cadena, matemáticas, fecha, DB/BMQL, matriz, URL, diccionario, JSON, XML).

• Acceso a atributos: Las variables miembro de CPQ (como line.attribute y transaction.attribute) se resaltan de forma diferente a las variables generales.

• Operadores: Los operadores matemáticos, lógicos y de asignación se estilizan de forma distinta, lo que te ayuda a detectar errores tipográficos de sintaxis como escribir = en lugar de ==.

⌨ Referencia de comandos

Usa la Paleta de comandos (Ctrl+Shift+P / Cmd+Shift+P) para activar estas acciones:

⚙ Ajustes de configuración

Configure estos ajustes en el settings.json de VS Code o a través de la interfaz del Editor de configuración:

{
  "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
}

🔧 Ajustes del formateador (.bmlbeautifyrc)

Coloque un archivo de configuración .bmlbeautifyrc en cualquier directorio para personalizar las reglas del formateador BML. Las opciones están modeladas según las estructuras de JS-beautify:

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

📂 Estructura del proyecto

El proyecto tiene una estructura de diseño modular con una segregación limpia de los servicios del editor BML, la red REST, las utilidades de prueba y la integración de IA:

├── 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

🚀 Instalación y configuración

1. Instale desde Marketplace: Busque "CPQ-BML" en el panel de Extensiones de VS Code (Ctrl+Shift+X / Cmd+Shift+X) y haga clic en Instalar.

2. Configuración inicial: En la primera carga, se abrirá automáticamente el Panel de configuración.

3. Configurar entornos: Introduzca los datos de su sitio, elija su método de autenticación y verifique la conexión.

4. Proteja sus credenciales: Use los comandos CPQ-BML: Set CPQ Password o CPQ-BML: Set CPQ Auth Token para almacenar de forma segura sus contraseñas o claves.

💻 Desarrollo local

Si desea ejecutar, personalizar o contribuir a esta extensión:

Requisitos previos

• Node.js (se recomienda v22 o una versión más reciente)

• Visual Studio Code

Pasos

1. Clonar el repositorio:

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

2. Instalar las dependencias:

   npm install

3. Compilar el proyecto:

   npm run compile

4. Ejecutar el host de extensión: Abra el espacio de trabajo raíz en VS Code y pulse F5 (o vaya a Run and Debug -> Launch Extension). Esto abrirá una ventana de Extension Development Host donde podrá probar la compatibilidad con BML de inmediato.

📄 Licencia y registro de cambios

• Licencia: Este proyecto está licenciado bajo la Licencia MIT.

• Registro de cambios: El historial detallado de versiones, adiciones y actualizaciones está disponible en CHANGELOG.md.

• Aviso legal: Esta extensión es un proyecto comunitario independiente y no está afiliada, patrocinada, respaldada ni asociada de ningún otro modo con Oracle Corporation o BigMachines.