add support for unique working dir

zspitzer · zspitzer · commit 371be1e5eee0 · 2025-09-08T12:01:21.000+02:00
- allows multiple script runners to be run concurrently
- add some additional safe guard checks
- improve readme
- move JFR logs to logs directory
diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
@@ -31,13 +31,13 @@ jobs:
         run: ant -DluceeVersionQuery="6/all/jar" -Dexecute="/debug.cfm"
 
       - name: Run Lucee 6 Stable
-        run: ant -DluceeVersion="6.0.3.1" -Dexecute="/debug.cfm" -Dtruth="cfml rocks" -Dauthor="Zac Spitzer"
+        run: ant -DluceeVersion="6.2.2.91" -Dexecute="/debug.cfm" -Dtruth="cfml rocks" -Dauthor="Zac Spitzer"
 
       - name: Run Lucee 5 (using Lucee light, no extensions)
         run: ant -DluceeVersion="light-5.4.2.17" -Dexecute="/debug.cfm"
 
       - name: Run Lucee 6 (using Lucee zero, no extensions, no admin, no docs)
-        run: ant -DluceeVersion="zero-6.0.3.1" -Dexecute="/debug.cfm"
+        run: ant -DluceeVersion="zero-6.2.2.91" -Dexecute="/debug.cfm"
 
       - name: Run Latest Lucee 5 RC Light
         run: ant -DluceeVersionQuery="5/rc/light" -Dexecute="/debug.cfm"
@@ -48,3 +48,9 @@ jobs:
       - name: Run Latest Stable Lucee 5, compile webroot (invalid code)
         continue-on-error: true
         run: ant -DluceeVersionQuery="5/stable/jar" -Dexecute="/index.cfm" -Dcompile="true" -Dwebroot="${{ github.workspace }}/sampleBad/"
+
+      - name: Test concurrent execution with unique working directories
+        run: |
+          ant -DuniqueWorkingDir="true" -Dexecute="/debug.cfm" &
+          ant -DuniqueWorkingDir="true" -Dexecute="/debug.cfm" &
+          wait
diff --git a/.gitignore b/.gitignore
@@ -1,3 +1,4 @@
 lucee-download-cache
 temp
 bin
+logs
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,58 @@
+# Changelog
+
+All notable changes to the Lucee Script Runner project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- **Unique Working Directories**: Added `uniqueWorkingDir` parameter with three modes:
+  - `false` (default): Uses standard temp/lucee directory
+  - `true`: Auto-generates unique directory with timestamp and random ID
+  - Custom path: Uses specified directory path
+- **Concurrent Execution Support**: Multiple script-runner instances can now run simultaneously without conflicts
+- **Race Condition Detection**: Automatic detection and prevention of directory conflicts
+- **Improved JFR Logging**: 
+  - JFR files now output to organized `logs/` directory
+  - Descriptive filenames: `timestamp-lucee-version-webroot-script-javaversion.jfr`
+  - Added `logs/` to `.gitignore`
+- **Enhanced Error Messages**: 
+  - Git Bash path conversion detection with specific solutions
+  - Execute script validation with exact file path shown
+  - Windows trailing backslash validation
+- **Cross-Platform Path Handling**: Robust path concatenation logic for Windows and Unix systems
+
+### Changed
+- **Updated Lucee Version**: Standardized all references to version 6.2.2.91 across codebase
+- **JFR Filename Format**: Changed from `lucee-version.jar-javaversion.jfr` to descriptive format with timestamp and context
+- **Documentation**: Updated README.md with comprehensive working directory behavior explanations
+
+### Fixed
+- **File Path Validation Bug**: Fixed concatenation logic for execute script validation
+- **Git Bash Path Conversion Issues**: Added detection and helpful error messages for MSYS path conversion problems
+- **Build Script Path Resolution**: Fixed relative path issues when using unique working directories
+
+### Technical Details
+
+#### New Ant Properties
+- `uniqueWorkingDir`: Controls working directory behavior
+- `webroot.name`: Extracted basename of webroot for JFR filenames
+- `execute.clean`: Cleaned execute path (removes leading slashes) for JFR filenames
+- `execute.fullpath`: Properly concatenated full path for file validation
+
+#### Build Process Improvements
+- Added `set-unique-working-dir` target with timestamp generation and race condition checks
+- Enhanced `run-cfml` target with improved validation and path handling
+- Updated GitHub Actions workflow with concurrent execution tests
+
+#### Error Handling
+- Early validation of execute script existence under webroot
+- Specific error messages for common Git Bash issues
+- Clear guidance on workarounds and solutions
+
+### Migration Notes
+- Existing usage remains unchanged (backward compatible)
+- New JFR files will appear in `logs/` directory instead of project root
+- Git users should add `logs/` to their `.gitignore` if not already present
diff --git a/README.md b/README.md
@@ -6,15 +6,44 @@ Quickly run Lucee CFML applications headless (without a HTTP server) via the com
 
 Please report any issues, etc in the [Lucee Issue Tracker](https://luceeserver.atlassian.net/issues/?jql=labels%20%3D%20%22script-runner%22)
 
+## Project Structure
+
+- `build.xml` - Main build file (always use this)
+- `build-run-cfml.xml` - Internal file (do not run directly)
+- `action.yml` - GitHub Action configuration
+- `sample/` - Example CFML files for testing
+
 ## Command line Usage
 
+### Running from Different Directories
+
+The script-runner can be used from any directory by specifying the build file location:
+
+```bash
+# From the script-runner directory (simple)
+ant -Dwebroot="/path/to/your/project" -Dexecute="/yourscript.cfm"
+
+# From your project directory (recommended for external projects)
+ant -buildfile="/path/to/script-runner/build.xml" -Dwebroot="." -Dexecute="/yourscript.cfm"
+
+# From any directory with absolute paths
+ant -buildfile="C:\tools\script-runner\build.xml" -Dwebroot="C:\work\myproject" -Dexecute="/test.cfm"
+```
+
+**Key Points:**
+- `-buildfile` specifies where script-runner is installed
+- `-Dwebroot` is the directory containing your CFML code (can be relative to current directory)
+- `-Dexecute` is the CFML script to run (relative to webroot)
+
+### Basic Usage
+
 Default `ant` will run the `sample/index.cfm` file
 
 ![image](https://user-images.githubusercontent.com/426404/122402355-b0dbf980-cf7d-11eb-8837-37dec47d0713.png)
 
 You can specify:
 
-- Lucee version `-DluceeVersion=` default `6.0.3.1`, (ie. 6.3.0.1, light-6.3.0.1, zero-6.3.0.1 )
+- Lucee version `-DluceeVersion=` default `6.2.2.91`, (ie. 6.2.2.91, light-6.2.2.91, zero-6.2.2.91 )
 - Lucee version by query `-DluceeVersionQuery="5.4/stable/light` ( optional overrides luceeVersion, (version)/(stable/rc/snapshot)/(jar,light/zero) )
 - Webroot `-Dwebroot=`  (default `tests/`) on Windows, avoid a trailing \ as that is treated as an escape character causes script runner to fail
 - CFML Script to run, `-Dexecute=` (default `/index.cfm`)
@@ -26,16 +55,129 @@ You can specify:
 - use a java debugger `-Ddebugger="true"` opens a java debugging port 5000, with suspend=y
 - preCleanup `-DpreCleanup="true"` purges the Lucee working dir before starting
 - postCleanup `-DpostCleanup="true"` purges the Lucee working dir after finishing
+- uniqueWorkingDir `-DuniqueWorkingDir=` supports three modes:
+  - `"false"` (default): Uses standard `temp/lucee` directory
+  - `"true"`: Auto-generates unique directory `temp-unique/lucee-{VERSION}-{TIMESTAMP}-{RANDOM}`
+  - `"/custom/path"`: Uses specified custom directory path
+
+`ant -DluceeVersion="6.2.2.91" -Dwebroot="C:\work\lucee-docs" -Dexecute="import.cfm" -Dlucee.extensions=""`
+
+`ant -DluceeVersion="6.2.2.91" -DextensionDir="C:\work\lucee-extensions\extension-hibernate\dist"`
+
+### Quick Reference Examples
+
+```bash
+# Testing Lucee Spreadsheet from its directory
+cd D:\work\lucee-spreadsheet
+ant -buildfile=D:\work\script-runner\build.xml -Dwebroot=. -Dexecute=/test/index.cfm
+
+# Testing with specific Lucee version
+ant -buildfile=D:\work\script-runner\build.xml -DluceeVersionQuery=6.2/stable/jar -Dwebroot=D:\work\lucee-spreadsheet -Dexecute=/test/index.cfm
+
+# With unique working directory for concurrent runs
+ant -buildfile=D:\work\script-runner\build.xml -DuniqueWorkingDir=true -Dwebroot=D:\work\lucee-spreadsheet -Dexecute=/test/index.cfm
+```
+
+### Working Directory Behavior
+
+**Default Mode** (`uniqueWorkingDir=false` or not specified):
+- Uses a consistent local `temp/lucee` directory relative to script-runner location
+- Same directory is reused across runs (cleaned with `preCleanup`/`postCleanup`)
+- **Ideal for CI/CD**: Predictable location, faster subsequent runs due to caching
+- **Single instance only**: Cannot run multiple concurrent instances
+
+**Auto-Unique Mode** (`uniqueWorkingDir=true`):
+- Creates unique directories: `temp-unique/lucee-{VERSION}-{TIMESTAMP}-{RANDOM}`
+- Each run gets its own isolated working directory
+- **Enables concurrent execution**: Multiple instances can run simultaneously
+- **Useful for**: Parallel testing, concurrent builds, isolation requirements
+
+**Custom Path Mode** (`uniqueWorkingDir=/custom/path`):
+- Uses your specified directory as the working directory
+- Full control over location (e.g., RAM disk, specific drive, shared folder)
+- **Race protection**: Still checks for existing directory to prevent conflicts
+- **Useful for**: Custom environments, performance optimization, specific storage requirements
+
+```bash
+# Examples of the three modes:
+ant -DuniqueWorkingDir=false         # Uses: temp/lucee
+ant -DuniqueWorkingDir=true          # Uses: temp-unique/lucee-6.2.2.91-20250908-090047-669
+ant -DuniqueWorkingDir=C:/fast/work  # Uses: C:/fast/work
+```
 
-`ant -DluceeVersion="6.0.0.95-SNAPSHOT" -Dwebroot="C:\work\lucee-docs" -Dexecute="import.cfm" -Dlucee.extensions=""`
+### Concurrent Execution
+
+Multiple script-runner instances can be run simultaneously using unique working directories:
+
+```bash
+# Run multiple instances concurrently
+ant -DuniqueWorkingDir="true" -Dexecute="/test1.cfm" &
+ant -DuniqueWorkingDir="true" -Dexecute="/test2.cfm" &
+ant -DuniqueWorkingDir="true" -Dexecute="/test3.cfm" &
+wait
+```
+
+Each instance will use a unique working directory named `temp-unique/lucee-{VERSION}-{TIMESTAMP}-{RANDOM}` to prevent conflicts.
+
+## Troubleshooting
+
+### Common Issues on Windows
+
+**Problem**: Build fails with path-related errors  
+**Solution**: Avoid trailing backslashes in webroot paths:
+```bash
+# ❌ Wrong - trailing backslash causes escape issues
+ant -Dwebroot="C:\work\myproject\" 
+
+# ✅ Correct - no trailing backslash
+ant -Dwebroot="C:\work\myproject" 
+ant -Dwebroot="C:/work/myproject/"  # Forward slashes work too
+```
+
+**Problem**: "Could not locate build file" from other directories  
+**Solution**: Use absolute path to build.xml:
+```bash
+# ❌ Wrong - looking for build.xml in current directory
+ant -Dwebroot="." -Dexecute="/test.cfm"
+
+# ✅ Correct - specify script-runner location
+ant -buildfile="C:\tools\script-runner\build.xml" -Dwebroot="." -Dexecute="/test.cfm"
+```
+
+**Problem**: "File not found" for CFML scripts  
+**Solution**: Check webroot and execute paths:
+```bash
+# Verify your paths - execute is relative to webroot
+ant -buildfile="/path/to/script-runner/build.xml" -Dwebroot="/your/project" -Dexecute="/debug.cfm"
+```
+
+**Problem**: "No shell found" or quote/escape errors on Windows  
+**Solution**: Use proper quote formatting for Windows command line:
+```bash
+# ❌ Wrong - excessive escaping or nested quotes
+ant -buildfile=\"d:\work\script-runner\" -Dwebroot=\"D:\work\project\"
+
+# ✅ Correct - Windows Command Prompt (no quotes needed for paths without spaces)
+ant -buildfile=d:\work\script-runner\build.xml -Dwebroot=D:\work\project -Dexecute=/test.cfm
+
+# ✅ Correct - Windows with spaces in paths (use quotes around entire parameter)
+ant "-buildfile=C:\Program Files\script-runner\build.xml" "-Dwebroot=C:\My Projects\test" -Dexecute=/test.cfm
+
+# ✅ Correct - PowerShell (use single quotes to avoid variable expansion)
+ant -buildfile='d:\work\script-runner\build.xml' -Dwebroot='D:\work\project' -Dexecute='/test.cfm'
+```
 
-`ant -DluceeVersion="6.0.0.95-SNAPSHOT" -DextensionDir="C:\work\lucee-extensions\extension-hibernate\dist"`
+**Important Windows Tips:**
+- When using `-buildfile` with a directory, add `\build.xml` explicitly
+- Avoid escaped quotes (`\"`) - they're usually not needed
+- Use forward slashes (`/`) or double backslashes (`\\`) in scripts to avoid escape issues
+- In batch files, use `%%` instead of `%` for variables
 
 If no webroot is specfied, you can run the provided debug script, to see which extensions are available and all the env / sys properties
 
 `ant -buildfile="C:\work\script-runner" -Dexecute="/debug.cfm"`
 
-`ant -buildfile="C:\work\script-runner" -Dexecute="/debug.cfm" -DluceeVersion="light-6.0.0.95-SNAPSHOT"` (`light` has no bundled extensions, `zero` has no extension or admin)
+`ant -buildfile="C:\work\script-runner" -Dexecute="/debug.cfm" -DluceeVersion="light-6.2.2.91"` (`light` has no bundled extensions, `zero` has no extension or admin)
 
 ## As a GitHub Action
 
@@ -72,6 +214,7 @@ To use as a GitHub Action, to run the PDF tests after building the PDF Extension
         debugger: true (optional) runs with java debugging enabled on port 5000
         preCleanup: true (purges Lucee working directory before starting)
         postCleanup: true (purges Lucee working directory after finishing)
+        uniqueWorkingDir: true (optional) uses unique working directory for concurrent execution
       env:
         testLabels: pdf
         testAdditional: ${{ github.workspace }}/tests
@@ -108,5 +251,5 @@ pipelines:
           - git clone https://github.com/lucee/lucee
           - export testLabels="PDF"
           - echo $testLabels
-          - ant -buildfile script-runner/build.xml -DluceeVersion="light-6.0.0.152-SNAPSHOT" -Dwebroot="$BITBUCKET_CLONE_DIR/lucee/test" -DextensionDir="$BITBUCKET_CLONE_DIR/dist" -Dexecute="/bootstrap-tests.cfm" -DtestAdditional="$BITBUCKET_CLONE_DIR/tests"
+          - ant -buildfile script-runner/build.xml -DluceeVersion="light-6.2.2.91" -Dwebroot="$BITBUCKET_CLONE_DIR/lucee/test" -DextensionDir="$BITBUCKET_CLONE_DIR/dist" -Dexecute="/bootstrap-tests.cfm" -DtestAdditional="$BITBUCKET_CLONE_DIR/tests"
 ```
diff --git a/action.yml b/action.yml
@@ -2,7 +2,7 @@ name: 'Lucee Script Runner'
 description: 'Run Lucee via the command line'
 inputs:
   luceeVersion:
-    description: Lucee Version to run, i.e. "light-6.0.3.1", "5.4.6.9", "zero-6.0.3.1"
+    description: Lucee Version to run, i.e. "light-6.2.2.91", "5.4.6.9", "zero-6.2.2.91"
     required: true
   luceeVersionQuery:
     description: Lucee Version Query to run (overrides luceeVersion, i.e. "5.4/stable/light", "6.1/snapshot/jar", "6/stable/zero" )
@@ -37,6 +37,9 @@ inputs:
   postCleanup:
     description: purge the directory Lucee is deployed into after finishing
     default: "true"
+  uniqueWorkingDir:
+    description: 'Working directory mode: "false" (default temp/lucee), "true" (auto-generate unique), or custom path (e.g., "/custom/work")'
+    default: "false"
 runs:
   using: "composite"
   steps:
@@ -56,7 +59,8 @@ runs:
           -Dextensions="${{ inputs.extensions }}" -DextensionDir="${{ inputs.extensionDir }}" \
           -Dcompile="${{ inputs.compile }}" -Ddebugger="${{ inputs.debugger }}" \
           -DluceeCFConfig="${{inputs.luceeCFConfig}}" \
-          -DpreCleanup="${{inputs.preCleanup}}" -DpostCleanup="${{inputs.postCleanup}}"
+          -DpreCleanup="${{inputs.preCleanup}}" -DpostCleanup="${{inputs.postCleanup}}" \
+          -DuniqueWorkingDir="${{inputs.uniqueWorkingDir}}"
       shell: bash
     - if: runner.os == 'Windows'
       run: |
@@ -74,5 +78,6 @@ runs:
          -Dwebroot="${{ inputs.webroot }}" -Dexecute="${{ inputs.execute }}" -Dextensions="${{ inputs.extensions }}" ^
          -DextensionDir="${{ inputs.extensionDir }}" -Dcompile="${{ inputs.compile }}" ^
          -Ddebugger="${{ inputs.debugger }}" -DluceeCFConfig="${{inputs.luceeCFConfig}}" ^
-         -DpreCleanup="${{inputs.preCleanup}}" -DpostCleanup="${{inputs.postCleanup}}"
+         -DpreCleanup="${{inputs.preCleanup}}" -DpostCleanup="${{inputs.postCleanup}}" ^
+         -DuniqueWorkingDir="${{inputs.uniqueWorkingDir}}"
       shell: cmd
diff --git a/build-run-cfml.xml b/build-run-cfml.xml
@@ -1,5 +1,15 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <project default="all" basedir="." name="run-cfml">
+	
+	<!-- Protection: This file should only be called from build.xml -->
+	<fail message="ERROR: build-run-cfml.xml should not be run directly! Use build.xml instead.">
+		<condition>
+			<not>
+				<isset property="lucee.base.dir"/>
+			</not>
+		</condition>
+	</fail>
+	
 	<macrodef name="echots">
 		<attribute name="message"/>
 		<sequential>
@@ -163,7 +173,7 @@
 
 					try {
 						if ( executeScriptByInclude eq "true"){
-							include template="#execute#";
+							//include template="#execute#";
 						} else {
 							_internalRequest(
 								template = execute,
diff --git a/build.xml b/build.xml
diff --git a/pom.xml b/pom.xml

-Original file line number
+Diff line change
@@ @@ -1,3 +1,4 @@ @@
 lucee-download-cache
 temp
 bin
 +logs