Tool & CI updates

.github/copilot-instructions.md

@@ -90,6 +90,85 @@ try { parse(json); } catch (JsonProcessingException e) { throw new FcliTechnical
 default -> throw new FcliBugException("Unexpected status: "+status);
 ```
 
+## Common Utility Classes
+The `fcli-common` module provides utility classes in `com.fortify.cli.common.util` for common operations. Always prefer these over direct JDK/third-party equivalents:
+
+**Note for AI assistants:** If you discover utility classes, methods, or patterns in `fcli-common/src/main/java/com/fortify/cli/common/util/` that are not documented below, or if documented utilities appear outdated/incorrect, please notify the user and suggest updates to this section.
+
+### Environment & Configuration
+- **`EnvHelper`**: Environment variable access with fcli-specific features
+  - Use `EnvHelper.env(name)` instead of `System.getenv()` — supports override via system properties (`fcli.env.VAR_NAME`) for testing
+  - Methods: `env()`, `envOrDefault()`, `requiredEnv()`, `envName()` (builds `FCLI_*` variable names), `asBoolean()`, `asInteger()`, `asCharArray()`
+  - Validation helpers: `checkSecondaryWithoutPrimary()`, `checkBothOrNone()`, `checkExclusive()`
+- **`FcliBuildProperties`**: Access build metadata
+  - Singleton: `FcliBuildProperties.INSTANCE`
+  - Methods: `getFcliVersion()`, `getFcliBuildDate()`, `getFcliActionSchemaVersion()`, `getFcliDocBaseUrl()`, etc.
+- **`FcliDataHelper`**: Manage fcli data directories and files
+  - Paths: `getFcliHomePath()`, `getFcliConfigPath()`, `getFcliStatePath()`
+  - File I/O: `saveFile()`, `readFile()`, `saveSecuredFile()` (encrypted), `readSecuredFile()`, `deleteFile()`, `deleteDir()`
+  - All paths are relative to fcli home directory; use `resolveFcliHomePath()` for absolute paths
+
+### Version Handling
+- **`SemVer`**: Semantic version parsing and comparison
+  - Constructor takes any string; `isProperSemver()` indicates validity
+  - Accessors: `getMajor()`, `getMinor()`, `getPatch()`, `getLabel()` (all return `Optional`)
+  - Comparison: `compareTo()`, `isCompatibleWith()` (checks major.minor compatibility)
+  - Example: `new SemVer("1.2.3").isCompatibleWith("1.3.0")` → `true` (same major, minor >= required)
+
+### Date/Time & Periods
+- **`DateTimePeriodHelper`**: Parse period strings to durations
+  - Supports: `ms`, `s`, `m`, `h`, `d`, `w`, `M` (months), `y` (years)
+  - Example: `"2h30m"` → 9000000 milliseconds
+  - Methods: `parsePeriodToMillis()`, `getCurrentDatePlusPeriod()`, `getCurrentOffsetDateTimePlusPeriod()`
+  - Create instances: `all()`, `byRange(Period.SECONDS, Period.DAYS)` for validation
+
+### File Operations
+- **`FileUtils`**: Advanced file/archive operations
+  - Archive extraction: `extractZip()`, `extractTarGZ()` with path resolver for security (zip-slip protection)
+  - Pattern matching: `processMatchingFileStream()`, `processMatchingDirStream()` — process files matching Ant-style globs (`**/*.jar`)
+  - Permissions: `setAllFilePermissions()`, `setSinglePathPermissions()`
+  - Utilities: `deleteRecursive()`, `isDirPathInUse()`, `moveFiles()`, `pathToString(path, separatorChar)`
+- **`ZipHelper`**: Stream-based zip entry processing
+  - Use `processZipEntries(inputStream, processor)` to iterate zip entries without full extraction
+  - Processor returns `Break.TRUE` to stop iteration early
+
+### String & Formatting
+- **`StringHelper`**: String manipulation utilities
+  - `indent(str, indentStr)` — indent multi-line strings
+
+### Reflection & Type Handling
+- **`JavaHelper`**: Type-safe casting and null-handling
+  - `as(obj, Class<T>)` → `Optional<T>` — safe cast, returns `Optional.empty()` if incompatible
+  - `is(obj, Class<T>)` → `boolean` — check if object is assignable to type
+  - `getOrCreate(obj, supplier)` — return obj if non-null, else create via supplier
+- **`ReflectionHelper`**: Reflective operations
+  - `getAllTypes(field)` — returns field type + generic type arguments as array
+  - `getGenericTypes(field)` — extract generic type arguments from parameterized fields
+  - `hasAnnotation()`, `getAnnotationValue()` — annotation introspection
+
+### Control Flow & Counters
+- **`Break`**: Enum for loop control (`Break.TRUE` / `Break.FALSE`)
+  - Use instead of `boolean` for clarity in processors/iterators
+  - Methods: `doBreak()`, `doContinue()`
+- **`Counter`**: Simple mutable counter
+  - Methods: `increase()`, `increase(long)`, `increase(Counter)`, `getCount()`
+
+### Console & Debug
+- **`ConsoleHelper`**: Terminal detection and width
+  - `hasTerminal()` — check if running in interactive terminal
+  - `getTerminalWidth()` — get terminal width for formatting
+  - `installAnsiConsole()`, `uninstallAnsiConsole()` — manage JAnsi integration
+- **`DebugHelper`**: Global debug flag
+  - `isDebugEnabled()`, `setDebugEnabled()`
+
+### Usage Principles
+1. **Prefer fcli utilities**: Use `EnvHelper.env()` over `System.getenv()`, `FcliDataHelper` over raw `Files` API for fcli data
+2. **Semantic versions**: Always use `SemVer` for version comparisons instead of string manipulation
+3. **Period parsing**: Use `DateTimePeriodHelper` for user-input duration strings (e.g., CLI options)
+4. **File patterns**: Use `FileUtils.processMatching*Stream()` for glob-based file filtering instead of manual pattern matching
+5. **Safe casting**: Use `JavaHelper.as()` for type-safe optional casting instead of `instanceof` + cast
+6. **Loop control**: Use `Break` enum in processors for clarity over `boolean` return values
+
 
 ## Detailed Style Guide (AI & Manual Edits)
 
@@ -106,6 +185,7 @@ default -> throw new FcliBugException("Unexpected status: "+status);
 
 ### Imports & Formatting
 - Always use explicit imports; avoid wildcard imports.
+- Always use imports, no fully qualified class names (unless this results in collision because same class name exists in mutliple packages)
 - Order: static imports (grouped), then normal imports alphabetically; keep separation between 3rd-party and internal logical groups only if automated tooling maintains it.
 - No unused imports; remove immediately.
 

.github/prompts/fix-imports.prompt.md

@@ -0,0 +1,119 @@
+# Replace Fully Qualified Class Names with Imports
+
+## Objective
+Find all fully qualified class names (FQCNs) used in Java code (not in import statements or package declarations) and replace them with simple class names after adding appropriate import statements.
+
+**Note:** Only update files within the `com.fortify.cli` packages. Do not modify third-party or external code.
+
+## Search Strategy
+
+1. **Initial Search**: Use regex search to find potential FQCNs:
+   ```regex
+   ^[^/\n]*[^import\s].*\b(com|org|java|javax|lombok)(\.[a-z][a-z0-9_])*\.[A-Z][a-zA-Z0-9]*
+   ```
+   - Search in: `**/com/fortify/cli/**/*.java`
+   - This pattern finds lines that contain FQCNs but are not import or package statements
+
+2. **Filter Results**: The search will include:
+   - Package declarations (ignore these)
+   - Import statements (ignore these)
+   - Actual FQCNs in code (these need fixing)
+
+## Common FQCN Patterns to Replace
+
+### Java Standard Library
+- `java.util.jar.JarFile` → `JarFile`
+- `java.util.jar.Manifest` → `Manifest`
+- `java.util.jar.Attributes` → `Attributes`
+- `java.util.function.Predicate` → `Predicate`
+- `java.util.Optional` → `Optional`
+
+### Third-party Libraries
+- `picocli.CommandLine.Model.CommandSpec` → `CommandLine.Model.CommandSpec` (after importing `picocli.CommandLine`)
+- `picocli.CommandLine.Command` → `CommandLine.Command` (after importing `picocli.CommandLine`)
+- `com.fasterxml.jackson.core.type.TypeReference` → `TypeReference`
+- `com.fasterxml.jackson.databind.JsonNode` → `JsonNode`
+
+### Lombok Annotations
+- `lombok.Builder` → `Builder`
+- `lombok.Data` → `Data`
+- `lombok.Getter` → `Getter`
+- `lombok.Setter` → `Setter`
+- `lombok.NoArgsConstructor` → `NoArgsConstructor`
+- `lombok.AllArgsConstructor` → `AllArgsConstructor`
+
+### Project Classes
+- `com.fortify.cli.common.util.FileUtils` → `FileUtils` (if not in same package)
+- Package-specific classes should use simple names with imports
+
+## Replacement Process
+
+For each FQCN found in actual code (not imports/packages):
+
+1. **Check Import Section**: Read the import section to see if the simple name is already imported
+2. **Check for Conflicts**: Verify no conflicting simple class name exists from a different package
+3. **Add Import**: Add the import statement in the appropriate location (keep imports sorted)
+4. **Replace FQCN**: Replace the fully qualified name with the simple name
+
+### Example Transformation
+
+**Before:**
+```java
+import java.io.File;
+import java.nio.file.Path;
+
+public class Example {
+    public void method(File file) {
+        try (java.util.jar.JarFile jar = new java.util.jar.JarFile(file)) {
+            java.util.jar.Manifest manifest = jar.getManifest();
+            java.util.jar.Attributes attrs = manifest.getMainAttributes();
+        }
+    }
+}
+```
+
+**After:**
+```java
+import java.io.File;
+import java.nio.file.Path;
+import java.util.jar.Attributes;
+import java.util.jar.JarFile;
+import java.util.jar.Manifest;
+
+public class Example {
+    public void method(File file) {
+        try (JarFile jar = new JarFile(file)) {
+            Manifest manifest = jar.getManifest();
+            Attributes attrs = manifest.getMainAttributes();
+        }
+    }
+}
+```
+
+## Special Cases
+
+### Nested Classes
+When replacing nested class references like `picocli.CommandLine.Model.CommandSpec`:
+1. Import the outer class: `import picocli.CommandLine;`
+2. Use qualified reference: `CommandLine.Model.CommandSpec`
+
+### Generic Type References
+For anonymous inner class instances like `new TypeReference<ArrayList<String>>() {}`:
+1. Import the type: `import com.fasterxml.jackson.core.type.TypeReference;`
+2. Use simple name: `new TypeReference<ArrayList<String>>() {}`
+
+### Same Package References
+If the FQCN refers to a class in the same package, just use the simple name without adding an import.
+
+## Verification Steps
+
+1. **Check Errors**: Use `get_errors` tool to check for compilation errors
+2. **Build Project**: Run `./gradlew build -x test` to verify everything compiles
+3. **Review Changes**: Ensure imports are added in the correct location and properly sorted
+
+## Notes
+
+- Follow the project's import ordering conventions (java.* first, then javax.*, then third-party, then project imports)
+- Use explicit imports; avoid wildcard imports (`import java.util.*`)
+- Remove any unused imports after refactoring
+- Keep related imports together for readability

.github/workflows/ci.yml

@@ -5,6 +5,10 @@ on:
   push:
     branches:
       - '**'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
 
 env:
   native_image_opts: --verbose -H:Log=registerResource:verbose -H:+PrintClassInitialization -march=compatibility
@@ -50,9 +54,14 @@ jobs:
           echo VERSION_PATCH=${patch} >> $GITHUB_ENV
 
       - name: DEV - Define release info
-        if: startsWith(github.ref, 'refs/heads/') && !env.DO_PROD_RELEASE
+        if: (startsWith(github.ref, 'refs/heads/') || github.event_name == 'pull_request') && !env.DO_PROD_RELEASE
         run: |
-          branch="${GITHUB_REF#refs/heads/}"
+          # For pull_request events, use head_ref (source branch); for push/workflow_dispatch, extract from ref
+          if [ "${{ github.event_name }}" == "pull_request" ]; then
+            branch="${{ github.head_ref }}"
+          else
+            branch="${GITHUB_REF#refs/heads/}"
+          fi
           tag="dev_${branch//[^a-zA-Z0-9_.-]/.}" # Replace all special characters by a dot
           tag="${tag//dev_dev./dev_}" # Remove duplicate dev-prefix
           tag="${tag//dev_rel./dev_}" # Remove rel-prefix
@@ -74,12 +83,7 @@ jobs:
             echo DO_DEV_RELEASE=true >> $GITHUB_ENV
           else 
             echo "Tag ${tag} does not exist, no development release will be published"
-          fi 
-
-      - name: PR - Define release info
-        if: github.event_name == 'pull_request' && !env.DO_PROD_RELEASE && !env.DO_RELEASE
-        run: |
-          echo DO_BUILD=true >> $GITHUB_ENV # Do a build with default settings for PRs
+          fi
 
       - name: Build release ${{env.RELEASE_VERSION}}
         if: env.DO_BUILD
@@ -104,6 +108,7 @@ jobs:
       version_major: ${{ env.VERSION_MAJOR }}
       version_minor: ${{ env.VERSION_MINOR }}
       version_patch: ${{ env.VERSION_PATCH }}
+      branch: ${{ env.BRANCH }}
 
   native_linux:
     name: native-image-linux
@@ -279,9 +284,6 @@ jobs:
     name: Trigger functional tests
     needs: [build, native_linux, native_mac, native_win, combine-artifacts]
     runs-on: ubuntu-latest
-    # TODO Also run on pull requests, but command below fails with (for example):
-    #  could not create workflow dispatch event: HTTP 422: No ref found for: refs/pull/849/merge (https://api.github.com/repos/fortify/fcli/actions/workflows/62959663/dispatches)
-    if: github.event_name != 'pull_request'
     steps:
       # Previously we had a workflow_run trigger on functional-tests.yaml, but:
       #  - This approach allows for starting functional tests a bit earlier (no need to wait for Docker builds)
@@ -290,7 +292,13 @@ jobs:
       - name: Check-out source code
         uses: actions/checkout@v4
       - run: | 
-          gh workflow run functional-tests.yml --ref ${GITHUB_REF} -f runId=${GITHUB_RUN_ID}
+          # Use branch output from build job if available, otherwise fall back to GITHUB_REF
+          if [ -n "${{ needs.build.outputs.branch }}" ]; then
+            ref="${{ needs.build.outputs.branch }}"
+          else
+            ref="${GITHUB_REF}"
+          fi
+          gh workflow run functional-tests.yml --ref "${ref}" -f runId=${GITHUB_RUN_ID}
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
@@ -321,7 +329,7 @@ jobs:
         if: needs.build.outputs.do_dev_release
         run: |
           gh release delete ${{ needs.build.outputs.release_tag }} -y || true
-          gh release create ${{ needs.build.outputs.release_tag }} -p -t "Development Release - ${GITHUB_REF#refs/heads/} branch" -n 'See `Assets` section below for latest build artifacts'
+          gh release create ${{ needs.build.outputs.release_tag }} -p -t "Development Release - ${{ needs.build.outputs.branch }} branch" -n 'See `Assets` section below for latest build artifacts'
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
@@ -341,32 +349,6 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
-      - name: PROD - Publish v{major}.{minor} tag
-        if: needs.build.outputs.do_prod_release
-        uses: richardsimko/update-tag@v1
-        with:
-          tag_name: v${{needs.build.outputs.version_major}}.${{needs.build.outputs.version_minor}}
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} 
-
-      - name: PROD - Publish v{major} tag
-        if: needs.build.outputs.do_prod_release
-        uses: richardsimko/update-tag@v1
-        with:
-          tag_name: v${{needs.build.outputs.version_major}}
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        # TODO If we publish a feature/patch for an older major version,
-        #      for example from the rel/v2.x branch,
-        #      this may cause the older major version to be tagged as 'latest'
-      - name: PROD - Publish latest tag
-        if: needs.build.outputs.do_prod_release
-        uses: richardsimko/update-tag@v1
-        with:
-          tag_name: latest
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-
   semantic_versions:
     name: Publish semantic versions
     if: needs.build.outputs.do_prod_release
@@ -376,6 +358,9 @@ jobs:
         semantic_version: 
           - v${{needs.build.outputs.version_major}}.${{needs.build.outputs.version_minor}}
           - v${{needs.build.outputs.version_major}}
+          # TODO If we publish a feature/patch for an older major version,
+          #      for example from the rel/v2.x branch,
+          #      this may cause the older major version to be tagged as 'latest'
           - latest
     runs-on: ubuntu-latest
     steps:
@@ -414,7 +399,13 @@ jobs:
       - name: Check-out source code
         uses: actions/checkout@v4
       - run: | 
-          gh workflow run docker.yml --ref ${GITHUB_REF} -f "releaseTag=${{ needs.build.outputs.release_tag }}" -f doPublish=${{ needs.build.outputs.do_release }}
+          # Use branch output from build job if available, otherwise fall back to GITHUB_REF
+          if [ -n "${{ needs.build.outputs.branch }}" ]; then
+            ref="${{ needs.build.outputs.branch }}"
+          else
+            ref="${GITHUB_REF}"
+          fi
+          gh workflow run docker.yml --ref "${ref}" -f "releaseTag=${{ needs.build.outputs.release_tag }}" -f doPublish=${{ needs.build.outputs.do_release }}
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}