|
| 1 | +# Copilot Instructions for AI Coding Agents — cbjavaloader |
| 2 | + |
| 3 | +## What this project is |
| 4 | + |
| 5 | +- A ColdBox module that embeds and exposes the JavaLoader library so CFML apps can dynamically load/compile Java classes and JARs. |
| 6 | +- Key pieces: `ModuleConfig.cfc` (module settings & DSL registration), `models/Loader.cfc` (public module API), `models/javaloader/` (JavaLoader, JavaProxy, JavaCompiler implementations), and `test-harness/` (integration test app). |
| 7 | + |
| 8 | +## Quick dev workflows (explicit) |
| 9 | + |
| 10 | +- Install deps: run the CommandBox installer at repo root and for the test harness: |
| 11 | + ```bash |
| 12 | + box install |
| 13 | + cd test-harness && box install |
| 14 | + ``` |
| 15 | +- Build module (packaging, docs): |
| 16 | + ```bash |
| 17 | + box task run taskFile=build/Build.cfc :projectName=`package show slug` :version=`package show version` |
| 18 | + ``` |
| 19 | +- Run tests (TestBox via provided VS Code tasks or CLI): |
| 20 | + ```bash |
| 21 | + box testbox run bundles=test-harness/tests --!recurse |
| 22 | + # or use the workspace VS Code task "Run TestBox Bundle" |
| 23 | + ``` |
| 24 | + |
| 25 | +## Project-specific conventions & patterns |
| 26 | + |
| 27 | +- WireBox DSL: `ModuleConfig.cfc` registers a custom DSL `javaloader` via `wireBox.registerDSL(...)`. Use inject="javaloader:ClassName" for DSL injections. |
| 28 | +- Main WireBox mappings: `binder.map("jl@cbjavaloader")` (internal JavaLoader) and `loader@cbjavaloader` (public module proxy, see `models/Loader.cfc`). Use `getWireBox().getInstance("loader@cbjavaloader")` in tests or handlers. |
| 29 | +- Persistent loader instance: `models/Loader.cfc` stores the JavaLoader instance in `server` scope under a hashed static key and uses `lock` for safe init/re-init — avoid re-instantiating directly; call `Loader.setup(moduleSettings)` or `Loader.getJavaLoader()`. |
| 30 | +- Java compilation: `models/javaloader/JavaCompiler.cfc` expects a JVM `tools.jar` compiler on the classpath; compiled jars are placed by default in `models/javaloader/tmp` (see module `settings.compileDirectory`). |
| 31 | + |
| 32 | +## Important files to consult (fast path) |
| 33 | + |
| 34 | +- `ModuleConfig.cfc` — module settings defaults and DSL registration. |
| 35 | +- `models/Loader.cfc` — public API that other apps use (`create`, `appendPath`, `getLoadedURLs`). |
| 36 | +- `models/javaloader/JavaLoader.cfc` — upstream JavaLoader implementation (large file, primary behavior). |
| 37 | +- `models/javaloader/JavaCompiler.cfc` — dynamic compilation logic and compiler discovery. |
| 38 | +- `build/Build.cfc` and `box.json` — packaging, test runner URL and build scripts used by CI. |
| 39 | +- `test-harness/` — runnable ColdBox app for integration tests; `test-harness/tests/specs/LoaderTest.cfc` shows expected behavior usage. |
| 40 | + |
| 41 | +## Integration points & external dependencies |
| 42 | + |
| 43 | +- JARs bundled under `models/javaloader/lib/` and `models/javaloader/support/*/lib/`; additional jars for testing live in `test-harness/jars/`. |
| 44 | +- The module relies on CommandBox and TestBox for build/test automation. CI uses `.github/workflows/*` (see repo root). |
| 45 | + |
| 46 | +## Safety, edge cases, and constraints agents must respect |
| 47 | + |
| 48 | +- Do not remove or replace the `server`-scoped loader without using the `Loader` API — other code/tests expect the single instance. |
| 49 | +- Java compilation may fail when the JVM compiler is not available; surface clear errors and point to `JavaCompiler.cfc` and `tools.jar` classpath as remediation. |
| 50 | + |
| 51 | +## Examples (from repo) |
| 52 | + |
| 53 | +- Injecting via DSL (see README & examples): |
| 54 | + ```cfml |
| 55 | + property name="hello" inject="javaloader:HelloWorld"; |
| 56 | + // or via WireBox mapping |
| 57 | + property name="javaloader" inject="loader@cbjavaloader"; |
| 58 | + ``` |
| 59 | +- Module settings (place in your app `ColdBox.cfc` under `moduleSettings.cbJavaLoader`): see `ModuleConfig.cfc` for keys like `loadPaths`, `sourceDirectories`, `compileDirectory`, `trustedSource`. |
| 60 | + |
| 61 | +## What to do next when editing code |
| 62 | + |
| 63 | +- When changing public behavior in `Loader.cfc` or DSL registration in `ModuleConfig.cfc`, update `test-harness/tests/specs/LoaderTest.cfc` or add a spec demonstrating the change. |
| 64 | +- Run `box testbox ...` after edits and ensure `test-harness` runner URL in `box.json` matches `build/Build.cfc` test runner if you rely on build tasks. |
| 65 | + |
| 66 | +Please review and tell me if you'd like added examples (e.g., a minimal handler that uses the loader), or if I should fold in more lines from the module-template instructions. |
0 commit comments