|
| 1 | +# CommandBox AI Coding Agent Instructions |
| 2 | + |
| 3 | +CommandBox is a CLI tool, package manager, and embedded server that serves both CFML (ColdFusion Markup Language) and BoxLang languages. Built on Java and CFML, it's a complex multi-layered application with a modular architecture. |
| 4 | + |
| 5 | +## Documentation Resources |
| 6 | + |
| 7 | +- **Official Docs**: https://commandbox.ortusbooks.com/ |
| 8 | +- **Context7 Docs**: https://context7.com/ortus-docs/commandbox-docs |
| 9 | + |
| 10 | +## Architecture Overview |
| 11 | + |
| 12 | +### Core Structure |
| 13 | + |
| 14 | +- **Shell Layer** (`src/cfml/system/Shell.cfc`): Interactive CLI shell with JLine integration |
| 15 | +- **Service Layer** (`src/cfml/system/services/`): Singleton services managed by WireBox DI |
| 16 | +- **Command Layer** (`src/cfml/system/modules_app/`): Modular command structure organized by domain |
| 17 | +- **Java Loader** (`src/java/`): Java bootstrap and classloader for CFML engine integration |
| 18 | + |
| 19 | +### Key Services Pattern |
| 20 | + |
| 21 | +Services are singletons injected via WireBox. Critical services include: |
| 22 | +- `ServerService`: Manages embedded CFML servers (Lucee, Adobe CF, BoxLang) |
| 23 | +- `PackageService`: Handles ForgeBox packages and dependencies |
| 24 | +- `CommandService`: Command discovery, parsing, and execution |
| 25 | +- `ConfigService`: Hierarchical configuration management |
| 26 | +- `EndpointService`: Pluggable artifact resolution (ForgeBox, HTTP, Git, etc.) |
| 27 | + |
| 28 | +## Command Development Patterns |
| 29 | + |
| 30 | +### Command Structure |
| 31 | + |
| 32 | +Commands extend `BaseCommand` and live in domain-specific modules: |
| 33 | +```cfml |
| 34 | +// File: src/cfml/system/modules_app/server-commands/commands/server/start.cfc |
| 35 | +component extends="commandbox.system.BaseCommand" aliases="start" { |
| 36 | + property name="serverService" inject="ServerService"; |
| 37 | +
|
| 38 | + function run() { |
| 39 | + // Command logic using injected services |
| 40 | + } |
| 41 | +} |
| 42 | +``` |
| 43 | + |
| 44 | +### Command Organization |
| 45 | + |
| 46 | +- Commands are organized by domain: `server-commands/`, `package-commands/`, etc. |
| 47 | +- Each module has `ModuleConfig.cfc` for ColdBox module configuration |
| 48 | +- Command aliases defined in component metadata enable shortcuts |
| 49 | + |
| 50 | +## Development Workflows |
| 51 | + |
| 52 | +### Building |
| 53 | + |
| 54 | +- **Build System**: Ant-based with complex multi-target process (`build/build.xml`) |
| 55 | +- **Core Build**: `ant -f build/build.xml build.cli` creates `box.jar` |
| 56 | +- **Full Distribution**: `ant -f build/build.xml build.cli.all` creates all formats |
| 57 | +- **Key Targets**: |
| 58 | + - `init`: Environment setup and directory structure |
| 59 | + - `resolve.libs`: Download Maven dependencies and CFML extensions |
| 60 | + - `build.cli`: Compile Java + CFML into JAR |
| 61 | + - `build.cli.exe/bin`: Native executables for Windows/Unix |
| 62 | + - `build.cli.jre`: Self-contained distributions with embedded JRE |
| 63 | + - `build.cli.deb/rpm`: Linux package formats |
| 64 | +- **Dependencies**: Maven repos for Java libs, ForgeBox for CFML modules |
| 65 | +- **Build Documentation**: See `build/BUILD.md` for complete process details |
| 66 | + |
| 67 | +### Testing |
| 68 | + |
| 69 | +- TestBox framework in `tests/` directory |
| 70 | +- Run tests via: `box testbox run` |
| 71 | +- Test structure mirrors source: `tests/cfml/system/` and `tests/cfml/commands/` |
| 72 | + |
| 73 | +### Module Development |
| 74 | + |
| 75 | +Commands are auto-discovered via WireBox scanning. New commands: |
| 76 | +1. Extend `BaseCommand` |
| 77 | +2. Place in appropriate domain module |
| 78 | +3. Use dependency injection for services |
| 79 | +4. Follow existing naming conventions |
| 80 | + |
| 81 | +## Critical Conventions |
| 82 | + |
| 83 | +### Dependency Injection |
| 84 | + |
| 85 | +```cfml |
| 86 | +// Standard service injection pattern |
| 87 | +property name="serverService" inject="ServerService"; |
| 88 | +property name="configService" inject="ConfigService"; |
| 89 | +property name="fileSystem" inject="FileSystem"; |
| 90 | +``` |
| 91 | + |
| 92 | +### Configuration Management |
| 93 | + |
| 94 | +- Global config: `~/.CommandBox/CommandBox.json` |
| 95 | +- Server config: `server.json` in project root |
| 96 | +- Hierarchical config resolution: CLI args > server.json > global config |
| 97 | +- Access via: `configService.getSetting('key.path')` |
| 98 | + |
| 99 | +### File System Abstraction |
| 100 | + |
| 101 | +Always use `fileSystem` service for cross-platform compatibility: |
| 102 | +```cfml |
| 103 | +fileSystem.resolvePath('./path') |
| 104 | +fileSystem.makeDirectory('./path') |
| 105 | +``` |
| 106 | + |
| 107 | +### Output and Formatting |
| 108 | + |
| 109 | +Use injected `print` service for all output: |
| 110 | +```cfml |
| 111 | +print.line( "Message" ).toConsole(); |
| 112 | +print.redLine( "Error message" ).toConsole(); |
| 113 | +``` |
| 114 | + |
| 115 | +### Code Formatting Examples |
| 116 | + |
| 117 | +```cfml |
| 118 | +// Correct formatting with required spacing: |
| 119 | +if( condition && anotherCondition ) { |
| 120 | + var result = someFunction( param1, param2 ); |
| 121 | + arrayAppend( myArray, { "key" : "value" } ); |
| 122 | +} |
| 123 | +
|
| 124 | +// Property alignment: |
| 125 | +property name="serverService" inject="ServerService"; |
| 126 | +property name="configService" inject="ConfigService"; |
| 127 | +property name="fileSystemUtil" inject="FileSystem"; |
| 128 | +``` |
| 129 | + |
| 130 | +## Server Management Specifics |
| 131 | + |
| 132 | +### Engine Support |
| 133 | + |
| 134 | +CommandBox supports multiple language engines: |
| 135 | +- **CFML Engines**: Lucee Server (default), Adobe ColdFusion |
| 136 | +- **BoxLang Engine**: Native BoxLang runtime support |
| 137 | +- **Custom WAR files**: Any Java-based web application |
| 138 | + |
| 139 | +### Server Lifecycle |
| 140 | + |
| 141 | +1. Server resolution via `serverEngineService.resolveEngine()` |
| 142 | +2. Runwar JAR execution with JVM args |
| 143 | +3. Configuration injection via `-D` properties |
| 144 | +4. Process monitoring and management |
| 145 | + |
| 146 | +## Module System |
| 147 | + |
| 148 | +### Built-in Modules |
| 149 | + |
| 150 | +Core modules in `src/cfml/modules/` are ForgeBox packages: |
| 151 | +- `coldbox-cli`: ColdBox framework commands |
| 152 | +- `testbox-cli`: TestBox testing commands |
| 153 | +- `commandbox-cfformat`: Code formatting |
| 154 | +- `commandbox-boxlang`: BoxLang engine support |
| 155 | + |
| 156 | +### Module Loading |
| 157 | + |
| 158 | +Modules auto-registered via: |
| 159 | +1. `box.json` dependencies |
| 160 | +2. WireBox auto-scanning |
| 161 | +3. ColdBox module system integration |
| 162 | + |
| 163 | +## Code Style |
| 164 | + |
| 165 | +### Mandatory Formatting Rules |
| 166 | + |
| 167 | +**ALL CFML code MUST adhere to `.cfformat.json` rules for readability:** |
| 168 | +- **Spacing**: Required around all operators, parentheses `()`, brackets `[]`, quotes |
| 169 | +- **Padding**: `brackets.padding: true`, `parentheses.padding: true`, `binary_operators.padding: true` |
| 170 | +- **Quotes**: Always use double quotes (`strings.quote: "double"`) |
| 171 | +- **Alignment**: Consecutive assignments, properties, and parameters must align |
| 172 | +- **Max columns**: 120 characters |
| 173 | +- **Indentation**: Tabs with 4-space equivalent (`tab_indent: true`, `indent_size: 4`) |
| 174 | + |
| 175 | +### Formatting Commands |
| 176 | + |
| 177 | +```bash |
| 178 | +# Format everything |
| 179 | +box run-script format |
| 180 | + |
| 181 | +# Start a watcher, type away, save and auto-format for you |
| 182 | +box run-script format:watch |
| 183 | +``` |
| 184 | + |
| 185 | +### Markdown Documentation |
| 186 | + |
| 187 | +**ALL Markdown files MUST adhere to `.markdownlint.json` rules:** |
| 188 | +- Follow project-specific markdownlint configuration |
| 189 | +- Maximum 2 consecutive blank lines (`no-multiple-blanks.maximum: 2`) |
| 190 | +- Inline HTML is allowed for specific formatting needs |
| 191 | +- Hard tabs are permitted in this project |
| 192 | +- Multiple H1 headings allowed for comprehensive documentation |
| 193 | + |
| 194 | +### Naming Conventions |
| 195 | + |
| 196 | +- Services: PascalCase (e.g., `ServerService`) |
| 197 | +- Methods: camelCase |
| 198 | +- Properties: camelCase |
| 199 | +- Commands: lowercase with hyphens for namespaces |
| 200 | + |
| 201 | +## Integration Points |
| 202 | + |
| 203 | +### Java Integration |
| 204 | + |
| 205 | +**Java Components** (`src/java/`): |
| 206 | +- **CLI Loader** (`cliloader/LoaderCLIMain.java`): Bootstrap loader that initializes CFML engine |
| 207 | +- **Authentication** (`com/ortussolutions/commandbox/authentication/`): Security components |
| 208 | +- **JGit Integration** (`com/ortussolutions/commandbox/jgit/`): Git operations |
| 209 | +- **Utilities**: Stream handling, version comparison, BOM detection |
| 210 | + |
| 211 | +**Java Usage in CFML**: |
| 212 | +- Extensive Java object creation for file I/O, networking, process management |
| 213 | +- JLine library for interactive shell features and command completion |
| 214 | +- Runwar JAR for embedded server management and deployment |
| 215 | +- Direct Java integration via `createObject('java', 'className')` pattern |
| 216 | + |
| 217 | +### External Dependencies |
| 218 | + |
| 219 | +- ForgeBox: Primary package repository |
| 220 | +- GitHub: Secondary artifact source |
| 221 | +- Maven repositories: Java dependencies |
| 222 | +- Custom endpoints: Pluggable artifact resolution |
| 223 | + |
| 224 | +## Multi-Language Support Notes |
| 225 | + |
| 226 | +CommandBox serves both CFML and BoxLang languages with full feature parity. The current branch `feature/rewrites-boxlang-support` enhances BoxLang integration: |
| 227 | +- **BoxLang**: Modern JVM language with CFML compatibility |
| 228 | +- **CFML**: Traditional ColdFusion Markup Language |
| 229 | +- **Unified CLI**: Same commands work across both languages |
| 230 | +- **Engine-specific modules**: `commandbox-boxlang` for BoxLang-specific features |
| 231 | +- **Configuration**: Server settings may vary between language engines |
0 commit comments