CPQ-BML VS Code 확장 프로그램

Oracle CPQ BigMachines Language (BML)를 위한 전문적이고 기능이 풍부한 Visual Studio Code 확장 프로그램입니다. 이 확장 프로그램은 IntelliSense, 구문 강조, 강력한 진단/린팅, 워크스페이스 전체 포맷팅, 원격 REST 통합, MCP 기반 AI 지원을 제공하여 CPQ 전문가를 위한 최고의 개발 환경을 제공합니다.

📖 목차

• 한눈에 보는 기능

• 주요 기능

  • 1. 언어 지원 및 IntelliSense

  • 2. 워크스페이스 포맷터 및 뷰티파이어

  • 3. BML 린터 및 실시간 진단

  • 4. Better Comments 및 문서 헤더

  • 5. 대화형 설정 대시보드 WebView

  • 6. 원격 REST 통합 및 동기화

  • 7. AI 통합을 위한 Model Context Protocol (MCP) 서버

  • 8. AI 에이전트 스킬 통합(AgentSkills.io)

  • 9. BML 컬러 테마

• ⌨ 명령어 참조

• ⚙ 구성 설정

• 🔧 포맷터 설정 (.bmlbeautifyrc)

• 📂 프로젝트 구조

• 🚀 설치 및 설정

• 💻 로컬 개발

• 📄 라이선스 및 변경 로그

Related MCP server: Salesforce CLI MCP Server

✨ 한눈에 보는 기능

• 🎨 BML 컬러 테마: 깊은 시맨틱 토큰 색상 지정을 제공하는 네 가지 맞춤형 에디터 테마.

• 💡 IntelliSense: 상황에 맞는 자동 완성, 시그니처 도움말, 매개변수 툴팁.

• 🔍 린터 및 진단: SQL 인젝션, 하드코딩된 비밀정보 등 보안 문제, Oracle 자체 BML 문서와 대조하여 검증된 컴파일/런타임 실패가 확실한 오류, 사용 중단된 API, 논리 오류를 감지하는 70개 이상의 실시간 검사.

• 📖 오프라인 도움말 뷰어: Docusaurus 스타일로 렌더링된 문서(:::note/:::warning 콜아웃 포함)가 모든 호버 툴팁에서 즉시 열리며 인터넷 연결이 필요 없습니다.

• 🛠 워크스페이스 전체 포맷팅: 디렉터리나 대상 폴더를 재귀적으로 뷰티파이합니다.

• ☁ REST 통합: BML 함수를 원격 CPQ 인스턴스에서 직접 동기화, 컴파일, 검증, 디버그, 배포합니다.

• 🤖 AI 에이전트 연결(MCP): 안전한 로컬 Model Context Protocol (MCP) 서버를 사용하여 AI를 통해 빌드하거나 디버그합니다.

• 🧠 AI 에이전트 스킬(AgentSkills.io): Claude Code와 같은 AI 어시스턴트에 깊은 CPQ 및 BML 도메인 지식을 주입하는 8개의 사전 컴파일된 시맨틱 스킬이 함께 제공됩니다.

• 📝 Better Comments: 작업, 태그, 지시문, 함수 헤더에 대해 뚜렷하게 구분되는 시각적 스타일을 제공합니다.

🔍 주요 기능

1. 언어 지원 및 IntelliSense

• 풍부한 구문 강조: BML 메서드, 제어 흐름 문(if, elif, else, for), 데이터베이스 쿼리(bmql), 연산자, 리터럴에 대한 완전한 문법 지원.

• 스니펫 라이브러리: 반복 구조, 일반적인 문자열 연산, JSON 조작, 시스템 함수에 대한 즉시 사용 가능한 상황 인지 코드 스켈레톤.

• 자동 완성 및 툴팁: Oracle CPQ 사양에 따라 입력할 때마다 시그니처, 반환 타입, 매개변수 체크리스트가 채워집니다.

• 오프라인 도움말 뷰어: 내장 함수에 대한 모든 호버 툴팁에는 📖 오프라인 도움말 읽기 링크가 포함되어 있어 인터넷 연결 없이 빠르고 독립 실행형 문서 패널이 열립니다. Docusaurus 스타일의 :::note/:::tip/:::warning 콜아웃을 원시 마크다운 텍스트가 아닌 적절한 색상 상자로 렌더링하며, 에디터에 맞춰진 테마를 사용하고, 열 때마다 단일 패널을 재사용하므로 매번 미리보기를 다시 실행하는 대신 반복 조회를 즉시 수행할 수 있습니다.

• 맞춤법 검사기 통합: cspell.json 정의가 미리 구성되어 CPQ 전용 함수(strtojavadate, jsonarrayrefid, bmql 등)가 맞춤법 오류를 트리거하지 않고 자동으로 지원됩니다.

2. 워크스페이스 포맷터 및 뷰티파이어

• 재귀적 포맷팅: CPQ-BML: Beautify / Format All BML Files in Workspace(cpqBml.beautifyWorkspace)를 실행하여 BML 파일을 재귀적으로 포맷합니다.

• 폴더 대상 지정 UI: 다중 선택 빠른 선택(quick-pick) 픽커가 워크스페이스 루트 경로와 폴더를 표시하여 특정 모듈을 대상으로 지정할 수 있습니다.

• CPQ 규칙: 들여쓰기, 간격, 중괄호 배치를 표준화하고, 키워드 not을 컴파일러가 요구하는 NOT으로 자동 대체하는 것과 같은 대문자 규칙을 적용합니다.

• 유연한 구성: 특정 디렉터리에 대해 로컬 .bmlbeautifyrc JSON 파일을 사용하여 포맷터 동작을 재정의할 수 있습니다.

3. BML 린터 및 실시간 진단

이 확장 프로그램은 CPQ에 업로드하기 전에 결함, 안티패턴, 취약점을 포착하기 위한 사용자 지정 BML 네이티브 정적 분석기를 포함합니다:

인라인 억제

주석을 사용하여 특정 린터 규칙을 세부적으로 우회할 수 있습니다. 지시문은 대소문자를 구분하지 않으며 줄 주석과 블록 주석 모두에서 작동합니다:

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

지원되는 지시문 스타일:

[!TIP] 코드 목록을 생략하면 모든 진단이 억제되며, 하나 이상의 bml-* 코드를 나열하면 해당 특정 규칙만 억제됩니다. 많은 진단에 대해 전구 빠른 수정(Ctrl+. 또는 Cmd+.)을 사용할 수 있어 세미콜론 스타일, 변수 오타, 서식 오류 또는 사용되지 않는 API를 즉시 자동 해결할 수 있습니다.

4. Better Comments 및 문서 헤더

주석을 분류된 작업, 상태 또는 시각적 강조로 스타일링하여 코드 가독성을 높입니다.

사용자 정의 태그 스타일링

지시문 및 블록 헤더

• Lint 및 서식 지시문: // bml-lint-disable-line 또는 /* beautify ignore:start */ 같은 주석은 제어 태그를 눈에 띄게 하면서도 방해되지 않도록 독특한 보라색 테두리로 스타일링됩니다.

• 표준 문서 헤더: Function Name:, Description:, Inputs: 또는 Returns:로 시작하는 함수 문서 블록은 자동으로 그룹화되어 연한 파란색 기울임꼴 글꼴로 색상이 지정됩니다.

5. 대화형 설정 대시보드 WebView

CPQ-BML: Open Settings(cpqBml.settings.open)를 사용하여 사용자 정의 그래픽 대시보드에서 연결 및 기능을 구성합니다:

• 연결 탭: 서버의 사이트 URL, 인증 체계 및 활성 API 자격 증명을 입력합니다.

• 환경 탭: 여러 샌드박스(예: Dev, Test, UAT, Production)를 저장하여 활성 대상을 전환합니다.

• 기능 탭: 깔끔한 UI에서 린팅 규칙, Better Comments 스타일링 및 일반 확장 프로그램 어시스턴트를 전환합니다.

• 보안 저장소 통합: VS Code Secret Storage API에 직접 연결됩니다. 자격 증명, 비밀번호 및 토큰은 OS 키체인에 저장되며 일반 텍스트 구성 파일에는 절대 기록되지 않습니다.

• 연결 테스트: 한 번의 클릭으로 설정 적용 직전에 원격 자격 증명과 사이트 연결 상태를 즉시 확인합니다.

6. 원격 REST 통합 및 동기화

CPQ 개발 워크플로우를 로컬 편집기 안에서 완전히 수행합니다:

• 코드 가져오기: 원격 서버에서 해당 메타데이터와 함께 Utility Library 함수 및 Commerce Process 함수(cpqBml.rest.pullLibraryFunctions, cpqBml.rest.pullCommerceFunctions)를 가져옵니다.

• 원격 검증 및 컴파일: CPQ-BML: Validate Current File Against CPQ를 실행하여 활성 문서에서 Oracle의 서버 측 컴파일러를 실행하고 구문 진단을 로컬에 표시합니다.

• 샌드박스 디버거: CPQ-BML: Debug Current Function on CPQ를 눌러 매개변수 선택기 대화 상자를 시작하고 테스트 값을 샌드박스 런타임에 보낸 다음 터미널에서 표준 출력을 검토합니다.

• 배포 제어: 개별 파일 저장, Utility Library 일괄 배포 또는 전체 Commerce Process 구성을 사용하여 수정된 코드를 즉시 배포합니다.

7. AI 통합을 위한 Model Context Protocol(MCP) 서버

이 확장 프로그램은 내장된 보안 Model Context Protocol(MCP) 서버를 실행하여 AI 코딩 어시스턴트(예: Claude Code)가 작업 영역의 코드를 안전하게 검사, 디버그 및 배포할 수 있게 합니다.

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

보안 모델

자격 증명, 쿠키 및 비밀 토큰은 확장 프로그램의 보안 컨텍스트 내에 유지됩니다. MCP 서버는 이러한 값을 AI 클라이언트에 노출하지 않습니다. 서버는 단지 실행자 역할만 하며 로컬 확장 프로그램 인스턴스를 통해 요청을 라우팅합니다.

AI 작업 격리

AI 에이전트가 MCP를 통해 파일 수정 또는 다운로드를 요청하면 확장 프로그램은 격리된 [variableName]-AI.bml 작업 복사본을 생성합니다. 이렇게 하면 에이전트가 로컬 스크립트를 덮어쓰는 것을 방지하고 커밋 전에 diff 도구로 변경 사항을 검토할 수 있습니다.

노출된 MCP 도구

• list_util_functions: 원격 Utility Library의 모든 함수를 열거합니다.

• list_commerce_functions: CPQ 인스턴스의 모든 Commerce 스크립트를 나열합니다.

• pull_function: 표준 BML을 가져와 로컬에 .bml 및 -meta.json 파일로 저장합니다.

• save_function: CPQ 환경에 업데이트를 적용합니다.

• validate_function: CPQ 서버 컴파일러를 쿼리하여 변경 사항을 검증합니다.

• debug_function: 테스트 매개변수로 함수를 원격으로 실행합니다.

• deploy_function / mass_deploy_util_functions: 개별 또는 일괄 함수를 배포합니다.

• deploy_commerce_process: 전체 프로세스 구성을 게시합니다.

• create_util_function: 새 Utility 함수를 스캐폴딩하고 게시합니다.

• create_override: 표준(시스템) 함수의 편집 가능한 재정의를 생성합니다 - 검증, 저장 또는 배포 전에 필요합니다.

• remove_override: 재정의된 표준 함수를 CPQ의 시스템 버전으로 되돌립니다(파괴적 작업이며 confirm:true가 필요합니다).

8. AI 에이전트 스킬 통합(AgentSkills.io)

CPQ-BML에는 AgentSkills.io 사양에 맞게 설계된 사전 컴파일된 "Agent Skills" 세트가 포함되어 있습니다. 이는 작업 영역과 상호 작용할 때 이러한 스킬을 기본적으로 파싱하는 AI 코딩 어시스턴트(예: Claude Code 또는 Cursor)에 깊은 도메인 지식을 주입합니다.

제로 구성 설정: 확장 프로그램 설정에서 MCP 서버를 활성화하면 CPQ-BML이 이러한 스킬을 작업 영역에 자동으로 등록합니다. 직접 실행해야 할 수동 설정 명령은 없습니다! 확장 프로그램 패키지를 작게 유지하고 작업 영역을 깨끗하게 유지하기 위해:

• 방대한 의미론적 지식 베이스는 빌드 시 고도로 최적화된 .br 아카이브로 압축됩니다.

• 런타임에는 확장 프로그램이 이 지식을 안전한 VS Code Global Storage 디렉터리로 투명하게 압축 해제합니다.

• AI 어시스턴트를 전역 저장소 위치로 안내하는 포인터 파일(예: .agents/skills.json, CLAUDE.md, .cursorrules)을 작업 영역에 자동으로 제공합니다.

확장 프로그램은 AI가 표준 Javascript 가정을 사용하여 BML을 무작정 편집하려고 시도하는 대신 다음에 대한 컨텍스트 인식 지침을 제공합니다:

• BML의 고유한 구문 제한 사항(예: var 또는 let 없음, === 대신 ==, ! 대신 NOT).

• 직접 데이터베이스 액세스와 BMQL 구문 비교.

• CPQ에서 dictionary, JSON 및 문자열 조작에 관한 모범 사례.

• 엔드투엔드 AI 개발 워크플로우의 일부로 CPQ-BML MCP 도구(pull_function, save_function, validate_function 등)를 올바르게 활용하는 방법.

AI는 이러한 컨텍스트 규칙을 실시간으로 동적으로 가져와 표준 LLM 코드 생성과 Oracle CPQ의 독점 런타임 사이의 간극을 메웁니다.

9. BML 색상 테마

네 가지 특수 테마가 확장 프로그램에 포함되어 있습니다:

• BML Dark

• BML Dark Default

• BML Light

• BML Light Default

[!NOTE] 구문 색상은 테마에 의해 결정됩니다. 확장 프로그램은 외부 테마에 재정의를 강제하지 않습니다. BML 테마 중 하나를 선택(Ctrl+K Ctrl+T / Cmd+K Cmd+T)하여 CPQ 고유의 토큰 색상을 확인하세요.

색상 세부 정보

• 분류된 함수: 내장 함수 범주(예: string, math, date, DB/BMQL, array, URL, dictionary, JSON, XML)에 고유한 색상이 할당됩니다.

• 속성 액세스: CPQ 멤버 변수(line.attribute, transaction.attribute 등)는 일반 변수와 다르게 강조 표시됩니다.

• 연산자: 수학, 논리 및 할당 연산자가 서로 다르게 스타일링되어 == 대신 =을 입력하는 것과 같은 구문 오타를 찾는 데 도움이 됩니다.

⌨ 명령 참조

명령 팔레트(Ctrl+Shift+P / Cmd+Shift+P)를 사용하여 다음 작업을 실행합니다:

⚙ 구성 설정

이 옵션은 VS Code의 settings.json 또는 설정 편집기 UI에서 구성할 수 있습니다:

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

🔧 포맷터 설정 (.bmlbeautifyrc)

.bmlbeautifyrc 구성 파일을 원하는 디렉터리에 배치하여 BML 포맷터 규칙을 사용자 지정할 수 있습니다. 옵션은 JS-beautify 구조를 모델로 삼았습니다:

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

📂 프로젝트 구조

이 프로젝트는 BML 편집기 서비스, REST 네트워킹, 테스트 유틸리티, AI 통합을 명확히 분리한 모듈식 설계 구조를 갖추고 있습니다:

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

🚀 설치 및 설정

1. 마켓플레이스에서 설치: VS Code 확장 패널(Ctrl+Shift+X / Cmd+Shift+X)에서 "CPQ-BML"을 검색하고 설치를 클릭합니다.

2. 초기 온보딩: 처음 로드하면 설정 대시보드가 자동으로 실행됩니다.

3. 환경 설정: 사이트 세부 정보를 입력하고 인증 방법을 선택한 후 연결을 확인합니다.

4. 자격 증명 보안: CPQ-BML: Set CPQ Password 또는 CPQ-BML: Set CPQ Auth Token 명령을 사용하여 비밀번호나 키를 안전하게 저장합니다.

💻 로컬 개발

이 확장 프로그램을 실행, 사용자 지정 또는 기여하려면:

전제 조건

• Node.js (v22 이상 권장)

• Visual Studio Code

단계

1. 저장소 복제:

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

2. 종속성 설치:

   npm install

3. 프로젝트 컴파일:

   npm run compile

4. 확장 호스트 실행: VS Code에서 루트 작업 공간을 열고 F5를 누릅니다(또는 Run and Debug -> Launch Extension으로 이동). 그러면 BML 지원을 즉시 테스트할 수 있는 확장 개발 호스트 창이 열립니다.

📄 라이선스 및 변경 로그

• 라이선스: 이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여됩니다.

• 변경 로그: 자세한 버전 기록, 추가 사항, 업데이트는 CHANGELOG.md에서 확인할 수 있습니다.

• 고지 사항: 이 확장 프로그램은 독립적인 커뮤니티 프로젝트이며 Oracle Corporation 또는 BigMachines와 제휴, 후원, 보증 또는 기타 어떠한 관련도 없습니다.