ColdFusion / CFML Debugger for VS Code

A feature-rich Visual Studio Code extension that brings native ColdFusion / CFML debugging support via the Debug Adapter Protocol (DAP) and an integrated virtual filesystem (cfrds://) for remote server-side file access over ColdFusion Remote Development Services (RDS).

📋 Table of Contents

• Features
• Architecture & Teardown Lifecycle
• Prerequisites
• Installation & Getting Started
• Usage Guide
  • 1. Connection Settings Panel
  • 2. Remote Virtual Filesystem (cfrds://)
  • 3. Managing Remote Files & Folders
  • 4. Setting & Syncing Breakpoints
  • 5. Starting a Debug Session (Launch & Attach)
  • 6. Stepping & Variable Inspection
• Debug Configurations (launch.json)
• Extension Settings
• Commands & Keyboard Shortcuts
• Troubleshooting & Diagnostics
• Development & Contributing
• License

✨ Features

• ⚡ Native DAP Integration: Full support for launch and attach debug requests with standard VS Code execution controls (Continue, Step Over, Step Into, Step Out, Pause, Terminate).
• 📂 Remote Virtual Filesystem (cfrds://): Seamlessly browse and open server-side ColdFusion files directly in VS Code without requiring local copies or network mounts.
• 🛠️ Remote File Management: Create, rename (F2), and delete (Delete / context menu) files and directories directly on the remote ColdFusion server via the sidebar tree view.
• 🔴 Breakpoint Synchronization: Set breakpoints in .cfm, .cfc, and .cfml files (local or remote cfrds://). Breakpoints are synced instantly to the ColdFusion RDS server.
• 🔍 Deep Scope & Variable Inspection: Inspect local and global ColdFusion scopes (VARIABLES, LOCAL, ARGUMENTS, ATTRIBUTES, REQUEST, SESSION, APPLICATION, SERVER, CGI, URL, FORM).
• 📦 Recursive WDDX Unwrapping: Parses complex ColdFusion structures, queries, arrays, and objects returned in WDDX payloads for accurate visualization in the Variables and Watch panels.
• 🎛️ Dedicated Activity Bar Sidebar:
  • Connection Settings: Embedded Webview panel with live connection status, server info, and one-click Connect / Disconnect controls.
  • Virtual Filesystem: Tree view for exploring remote server directories.
  • Debug Sessions: View active RDS debugger sessions and thread states.
• 🧹 Graceful Teardown: Automatically clears breakpoints from the server, resumes suspended threads, stops the RDS debug session, and closes virtual editor tabs on disconnect or VS Code exit.

🏗️ Architecture & Teardown Lifecycle

┌─────────────────────────────────────────────────────────────────────────┐
│                           VS Code Extension Host                        │
│                                                                         │
│  ┌────────────────────────┐         ┌────────────────────────────────┐  │
│  │ Connection Settings    │         │  Virtual Filesystem Provider   │  │
│  │ (Webview Panel)        │         │  (cfrds://)                    │  │
│  └───────────┬────────────┘         └───────────────┬────────────────┘  │
│              │                                      │                   │
│              ▼                                      ▼                   │
│  ┌───────────────────────────────────────────────────────────────────┐  │
│  │            ConnectionManager (Singleton RDS State)                │  │
│  │            - Manages @bokic/cfrds Server instance                 │  │
│  │            - Long-polling RDS Debugger Event Loop                 │  │
│  │            - Central Breakpoint Synchronizer                      │  │
│  └──────────────────────────────────┬────────────────────────────────┘  │
│                                     │                                   │
│                                     ▼                                   │
│  ┌───────────────────────────────────────────────────────────────────┐  │
│  │            CfmlDebugAdapterFactory (Inline DAP)                   │  │
│  │            - Translates DAP requests ↔ RDS protocol                │  │
│  │            - Maps stack frames & scopes                           │  │
│  └──────────────────────────────────┬────────────────────────────────┘  │
└─────────────────────────────────────┼───────────────────────────────────┘
                                      │ HTTP / RDS Protocol (Port 8500)
                                      ▼
                       ┌─────────────────────────────┐
                       │  Adobe ColdFusion Server    │
                       │  - RDS Security / Debugger  │
                       └─────────────────────────────┘

Clean Teardown Sequence

To prevent leaving threads paused or orphan debug sessions open on the ColdFusion server, disconnecting or closing VS Code triggers an automated teardown sequence:

1. Clear Server Breakpoints: Sends debuggerClearAllBreakpoints to purge all breakpoints registered during the session.
2. Resume Suspended Thread: Sends debuggerContinue to release any paused ColdFusion worker thread.
3. Stop RDS Debug Session: Invokes debuggerStop to notify the CF server that the debugging session has ended.
4. Clean Workspace Tabs: Automatically identifies and closes all open cfrds:// virtual document tabs in VS Code.

⚙️ Prerequisites

• VS Code: Version 1.90.0 or higher.
• Node.js: Version 18.x or higher (for building/packaging).
• ColdFusion Server: Adobe ColdFusion server with RDS (Remote Development Services) enabled and RDS security configured.

🚀 Installation & Getting Started

[!TIP] Prebuilt .vsix package releases are available for direct download at GitHub Releases.

1. Build from Source

# Clone the repository
git clone https://github.com/bokic/vscode_cfml_debugger.git
cd vscode_cfml_debugger

# Install dependencies
npm install

# Build extension
npm run compile

2. Run in Development Mode

Press F5 in VS Code to open an Extension Development Host window with the ColdFusion Debugger loaded.

3. Package as VSIX

To generate an installable .vsix extension package:

./build-vsix.sh
# or using npm:
npm run package

4. Installing the VSIX Package

Option 1: Via VS Code Graphical Interface

1. Open VS Code.
2. Open the Extensions panel (Ctrl+Shift+X / Cmd+Shift+X).
3. Click the ... (More Actions) menu at the top-right of the Extensions panel.
4. Click Install from VSIX...
5. Select the generated .vsix file (e.g. vscode-cfml-debugger-0.1.0.vsix).

Option 2: Via Terminal Command Line

code --install-extension vscode-cfml-debugger-0.1.0.vsix

📖 Usage Guide

1. Connection Settings Panel

Click on the ColdFusion Debugger icon in the Activity Bar to reveal the sidebar panels.

1. In the Connection Settings webview panel, enter:
   • Hostname: (e.g., localhost or remote IP)
   • Port: ColdFusion web port (default: 8500)
   • Username: RDS / Admin username (default: admin)
   • Password: RDS / Admin password
   • Path: Web root path on the server (e.g., / or /var/www/html)
2. Click Connect.
3. Once connected, the status indicator turns green and displays server details (CF Server Version, Client Version, Root Path, Debug Session ID).

2. Remote Virtual Filesystem (cfrds://)

• Expand the Virtual Filesystem panel in the sidebar to browse server directories.
• Click any .cfm or .cfc file to open it directly from the remote server.
• Files open under the cfrds:// URI scheme and feature full syntax highlighting and breakpoint support.

3. Managing Remote Files & Folders

You can perform remote file operations directly inside the Virtual Filesystem tree view:

• New File: Click the + icon in the panel toolbar (or right-click a folder -> New File...).
• New Folder: Click the folder icon in the panel toolbar (or right-click -> New Folder...).
• Rename: Select a file or folder and press F2 (or right-click -> Rename).
• Delete: Select a file or folder and press Delete (or right-click -> Delete). A modal confirmation prompt prevents accidental deletion.

4. Setting & Syncing Breakpoints

• Open any .cfm, .cfc, or .cfml file (local workspace file or remote cfrds:// file).
• Click in the editor gutter or press F9 to toggle breakpoints.
• If connected, breakpoints sync immediately to the server. If disconnected, breakpoints automatically sync as soon as a server connection is established.

5. Starting a Debug Session (Launch & Attach)

• Open the Debug view (Ctrl+Shift+D / Cmd+Shift+D).
• Select Launch ColdFusion Debugger or Attach to ColdFusion Debugger from the debug dropdown and press F5.
• The debug adapter reuses the active RDS connection maintained by ConnectionManager.

6. Stepping & Variable Inspection

When execution pauses at a breakpoint:

• Use the Debug Control Toolbar:
  • ⏸️ Pause / ▶️ Continue (F5)
  • ↷ Step Over (F10)
  • ↳ Step Into (F11)
  • ↲ Step Out (Shift+F11)
• Variables Window: Expand ColdFusion scopes (VARIABLES, LOCAL, ARGUMENTS, ATTRIBUTES, REQUEST, SESSION, APPLICATION, etc.). Complex objects and queries are recursively parsed from WDDX.
• Watch Panel & Hover: Add expressions to the Watch window or hover over variables in the editor to evaluate their values in real time.

🛠️ Debug Configurations (launch.json)

Add debug configurations to your project's .vscode/launch.json:

Launch Configuration

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "cfml",
      "request": "launch",
      "name": "Launch ColdFusion Debugger",
      "serverUrl": "http://localhost:8500",
      "username": "admin",
      "password": "your-password",
      "webRoot": "${workspaceFolder}",
      "stopOnEntry": false,
      "trace": false,
      "virtualFs": {
        "enabled": true,
        "scheme": "cfrds"
      }
    }
  ]
}

Attach Configuration

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "cfml",
      "request": "attach",
      "name": "Attach to ColdFusion Debugger",
      "serverUrl": "http://localhost:8500",
      "username": "admin",
      "password": "your-password",
      "stopOnEntry": true,
      "trace": false
    }
  ]
}

⚙️ Extension Settings

Configure workspace or global settings under cfmlDebugger in VS Code Settings:

⌨️ Commands & Keyboard Shortcuts

Extension Commands

Context Keybindings

🔍 Troubleshooting & Diagnostics

Output Channel Logs

The extension maintains an integrated logging output channel.

• Open via Command Palette (Ctrl+Shift+P / Cmd+Shift+P) -> CFML: Show Debug Log
• Or view the Output tab in VS Code and select ColdFusion Debugger from the dropdown menu.

Common Issues & Solutions

1. Max session count reached error:

   • Cause: ColdFusion allows a limited number of concurrent RDS debugging sessions.
   • Fix: Restart the ColdFusion Application Server or clear existing debugging sessions in CF Administrator.

2. Cannot connect to RDS:

   • Verify RDS is enabled in ColdFusion Administrator -> Security -> RDS.
   • Check firewall rules for port 8500 (or your custom CF port).
   • Ensure username/password credentials match CF Administrator RDS settings.

3. Breakpoints not hitting:

   • Ensure local source file paths match server web root mappings or use the cfrds:// Virtual Filesystem to open files directly from the server.
   • Check that line numbers contain executable CFML/CFScript code.

🧑‍💻 Development & Contributing

Directory Structure

src/
├── extension.ts                              # Extension entry point & command registration
├── cfml/
│   └── connectionManager.ts                  # Singleton RDS connection, event loop & teardown
├── debugAdapter/
│   ├── cfmlDebugAdapterFactory.ts            # DAP inline adapter factory
│   └── cfmlDebugSession.ts                   # DAP protocol implementation
├── panels/
│   └── cfmlSettingsViewProvider.ts           # Connection Settings webview provider & UI
├── virtualFs/
│   ├── cfmlVirtualFsProvider.ts              # In-memory FileSystemProvider (cfrds://)
│   ├── cfmlVirtualFsTreeDataProvider.ts      # VFS Tree view provider
│   └── cfmlDebugSessionsTreeDataProvider.ts  # Active Debug Sessions tree view
└── utils/
    ├── logger.ts                             # Central output channel logger
    ├── pathUtils.ts                          # Path normalization & mapping helpers
    └── wddxParser.ts                         # WDDX XML recursive structure parser

Scripts

npm run compile   # Transpile TypeScript to JS
npm run watch     # Run tsc in watch mode
npm run lint      # Run ESLint check
npm run test      # Run test suite
npm run package   # Package extension into .vsix file

📄 License

This project is licensed under the MIT License.