ci(github): enhance workflows and repository configuration

Author: mrz1836

.github/.env.shared

@@ -40,22 +40,25 @@ SECONDARY_RUNNER=ubuntu-24.04          # Set identical to PRIMARY_RUNNER if you
 # ───────────────────────────────────────────────────────────────────────────────
 ENABLE_CODE_COVERAGE=true              # Enable code coverage reporting (upload to Codecov)
 ENABLE_FUZZ_TESTING=true               # Enable fuzz running tests (requires Go 1.18+)
-ENABLE_LINT=true                       # Enable linting steps (golangci-lint)
+ENABLE_GO_LINT=true                    # Enable Go code linting steps (golangci-lint)
 ENABLE_RACE_DETECTION=true             # Enable Go's race detector in tests (-race flag)
 ENABLE_SECURITY_SCANS=true             # Enable tools like gitleaks, govulncheck, nancy
 ENABLE_STATIC_ANALYSIS=true            # Enable static analysis jobs (go vet)
-ENABLE_VERBOSE_TEST_OUTPUT=true        # Enable verbose output for test runs (can slow down CI)
+ENABLE_VERBOSE_TEST_OUTPUT=false       # Enable verbose output for test runs (can slow down CI)
+ENABLE_YAML_LINT=true                  # Enable YAML format validation (prettier with editorconfig)
 MAKEFILE_REQUIRED=true                 # Enforce the presence of Makefile for builds (future feature)
 
 # ───────────────────────────────────────────────────────────────────────────────
 # ENV: Tool Versions & Config
 # ───────────────────────────────────────────────────────────────────────────────
 GITLEAKS_NOTIFY_USER_LIST=@mrz1836                # User(s) to notify when gitleaks secrets are found (user,user2)
-GITLEAKS_VERSION=8.27.2                           # Version of gitleaks to install and use (X.Y.Z)
-GORELEASER_VERSION=v2.10.2                        # Version of goreleaser to install and use (vX.Y.Z)
-GOVULNCHECK_VERSION=v1.1.4                        # Version of govulncheck to use for Go vuln scanning (vX.Y.Z)
+GITLEAKS_VERSION=8.27.2                           # Version of gitleaks to install and use (X.Y.Z) (https://github.com/gitleaks/gitleaks)
+GORELEASER_VERSION=v2.11.0                        # Version of goreleaser to install and use (vX.Y.Z) (https://github.com/goreleaser/goreleaser)
+GOVULNCHECK_VERSION=v1.1.4                        # Version of govulncheck to use for Go vuln scanning (vX.Y.Z) (https://pkg.go.dev/golang.org/x/vuln)
 NANCY_EXCLUDES=CVE-2024-38513,CVE-2022-21698,CVE-2023-45142  # Known acceptable CVEs (cve,cve2,...)
-NANCY_VERSION=v1.0.51                             # Version of nancy to install and use (vX.Y.Z)
+NANCY_VERSION=v1.0.51                             # Version of nancy to install and use (vX.Y.Z) (https://github.com/sonatype-nexus-community/nancy)
+NODE_VERSION=20                                   # Node.js version for prettier and other tools (major version)
+PRETTIER_VERSION=3.6.2                            # Version of prettier to use for YAML validation (X.Y.Z) (https://www.npmjs.com/package/prettier)
 
 # ───────────────────────────────────────────────────────────────────────────────
 # ENV: Stale Workflow Configuration

.github/.prettierignore

@@ -0,0 +1,73 @@
+# Directories managed by package managers or VCS
+node_modules/
+vendor/
+.git/
+
+# Build outputs
+dist/
+build/
+
+# Coverage artifacts
+coverage/
+*.cover
+*.cov
+coverage.txt
+coverage.html
+
+# Minified assets
+*.min.js
+*.min.css
+
+# Generated source code
+*.generated.*
+**gen.go
+mock**.go
+*.pb.go
+*.pb.gw.go
+**/packaged.yaml
+
+# Compiled binaries
+*.exe
+*.dll
+*.so
+*.dylib
+*.test
+*.out
+
+# Temporary / swap files
+*.tmp
+*.temp
+*.swp
+*.swo
+*~
+
+# IDE metadata
+.idea/
+.vscode/
+*.iml
+
+# Dependency locks
+go.sum
+package-lock.json
+yarn.lock
+
+# Data exports
+*.json
+*.csv
+*.tsv
+*.sql
+
+# Documentation & licenses
+*.md
+LICENSE
+CHANGELOG
+CITATION.cff
+
+# Build & lint configs
+**/.golangci.json
+**/.golangci.yml
+**/.golangci.yaml
+**/.env.shared
+**/Makefile
+**/makefile
+**/*.mk

.github/.prettierrc.yml

@@ -0,0 +1,40 @@
+# ------------------------------------------------------------------------------------
+#  Prettier Configuration
+#
+#  Purpose: Ensures consistent YAML formatting across all tools (Prettier, IDEs)
+#  Location: .github directory (preferred for project-specific configs)
+#
+#  Maintainer: @mrz1836
+#
+# ------------------------------------------------------------------------------------
+
+# Print width (line length limit)
+printWidth: 80
+
+# Indentation
+tabWidth: 2
+useTabs: false
+
+# Quotes
+singleQuote: false # Use double quotes for consistency
+
+# Brackets and spacing (applies to JS/JSON objects, not YAML arrays)
+bracketSpacing: false # Keep consistent with YAML array formatting
+bracketSameLine: false
+
+# Array and object formatting
+trailingComma: "none" # No trailing commas in YAML
+
+# Line endings (should match .editorconfig)
+endOfLine: "lf"
+
+# Prose formatting (for Markdown in YAML)
+proseWrap: "preserve"
+
+# YAML-specific settings
+overrides:
+  - files: "*.{yml,yaml}"
+    options:
+      printWidth: 120 # Allow longer lines for YAML workflow files
+      bracketSpacing: false
+      singleQuote: false

.github/AGENTS.md

@@ -469,7 +469,7 @@ Code must be cleanly formatted and pass all linters before being committed.
 go fmt ./...
 goimports -w .
 gofumpt -w .
-golangci-lint run
+make lint
 go vet ./...
 ```
 
@@ -481,6 +481,33 @@ platforms.
 
 <br/>
 
+### 💄 Prettier (YAML Formatting)
+
+YAML files must be formatted consistently using Prettier to ensure clean diffs and readable configuration files.
+
+**Local Setup:**
+```bash
+# Install prettier locally
+npm init -y && npm install --save-dev prettier
+```
+
+**Format YAML files:**
+```bash
+# Check formatting
+npx prettier "**/*.{yml,yaml}" --check --config .github/.prettierrc.yml --ignore-path .github/.prettierignore
+
+# Fix formatting issues
+npx prettier "**/*.{yml,yaml}" --write --config .github/.prettierrc.yml --ignore-path .github/.prettierignore
+```
+
+**Configuration Files:**
+* [`.github/.prettierrc.yml`](.prettierrc.yml) - Prettier configuration settings
+* [`.github/.prettierignore`](.prettierignore) - Files and patterns to ignore during formatting
+
+> CI automatically validates YAML formatting using the same prettier configuration. All YAML files must pass formatting checks before merge.
+
+<br/>
+
 ---
 
 <br/>
@@ -505,13 +532,22 @@ We use the `testify` suite for unit tests. All tests must follow these conventio
 * Mock external dependencies — tests should be fast and deterministic
 * Use descriptive test names that explain the scenario being tested
 * Test error cases — ensure your error handling actually works
+* Handle all errors in tests properly:
+	* `os.Setenv()` returns an error - use `require.NoError(t, err)`
+	* `os.Unsetenv()` returns an error - use `require.NoError(t, err)`
+	* `db.Close()` in defer statements - wrap in anonymous function: `defer func() { _ = db.Close() }()`
+	* Deferred `os.Setenv()` for cleanup - wrap in anonymous function to ignore error
 
 Run tests locally with:
-
 ```bash
 go test ./...
 ```
 
+Or use our makefile:
+```bash
+make test
+```
+
 > All tests must pass in CI prior to merge.
 
 <br/>
@@ -1049,7 +1085,7 @@ CI automatically runs on every PR to verify:
 * Linting (`make lint`)
 * Tests (`make test`)
 * Fuzz tests (if applicable) (`make run-fuzz-tests`)
-* This codebase uses GitHub Actions; test workflows reside in `.github/workflows/fortress.yml`
+* This codebase uses GitHub Actions; test workflows reside in `.github/workflows/fortress.yml` and `.github/workflows/fortress-test-suite.yml`.
 * Pin each external GitHub Action to a **full commit SHA** (e.g., `actions/checkout@2f3b4a2e0e471e13e2ea2bc2a350e888c9cf9b75`) as recommended by GitHub's [security hardening guidance](https://docs.github.com/en/actions/security-guides/security-hardening-for-github-actions#using-pinned-actions). Dependabot will track and update these pinned versions automatically.
 
 Failing PRs will be blocked. AI agents should iterate until CI passes.

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -1,7 +1,7 @@
 name: Bug report
 description: Report incorrect behavior, test failure, or unexpected output in this Go library
 title: "[Bug] <brief description of the issue>"
-labels: [ "bug-p3" ]
+labels: ["bug-p3"]
 assignees:
   - icellan
 body:

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -1,7 +1,7 @@
 name: Feature request
 description: Suggest an idea or improvement for this project
 title: "[Feature] <brief description of feature>"
-labels: [ "idea" ]
+labels: ["idea"]
 assignees:
   - icellan
 body:

.github/ISSUE_TEMPLATE/question.yml

@@ -1,7 +1,7 @@
 name: Question
 description: General template for asking a question related to this project
 title: "[Question] <your topic here>"
-labels: [ "question" ]
+labels: ["question"]
 assignees:
   - icellan
 body:

.github/actions/load-env/action.yml

@@ -15,15 +15,15 @@
 #
 # ------------------------------------------------------------------------------------
 
-name: 'Load Environment Variables'
-description: 'Loads environment variables from .github/.env.shared and outputs as JSON'
+name: "Load Environment Variables"
+description: "Loads environment variables from .github/.env.shared and outputs as JSON"
 
 outputs:
   env-json:
-    description: 'JSON object containing all environment variables'
+    description: "JSON object containing all environment variables"
     value: ${{ steps.load-env.outputs.env-json }}
   primary-runner:
-    description: 'Primary runner OS extracted from environment variables'
+    description: "Primary runner OS extracted from environment variables"
     value: ${{ steps.load-env.outputs.primary-runner }}
 
 runs:

.github/actions/warm-cache/action.yml

@@ -8,32 +8,32 @@
 #
 # ------------------------------------------------------------------------------------
 
-name: 'Warm Go Caches'
-description: 'Warm Go module and build caches for the specified Go version and OS'
+name: "Warm Go Caches"
+description: "Warm Go module and build caches for the specified Go version and OS"
 
 inputs:
   go-version:
-    description: 'Go version to use'
+    description: "Go version to use"
     required: true
   matrix-os:
-    description: 'Operating system for the runner'
+    description: "Operating system for the runner"
     required: true
   matrix-name:
-    description: 'Display name for the matrix configuration'
+    description: "Display name for the matrix configuration"
     required: true
   enable-verbose:
-    description: 'Enable verbose output'
+    description: "Enable verbose output"
     required: false
-    default: 'false'
+    default: "false"
   go-primary-version:
-    description: 'Primary Go version for comparison'
+    description: "Primary Go version for comparison"
     required: true
   go-secondary-version:
-    description: 'Secondary Go version for comparison'
+    description: "Secondary Go version for comparison"
     required: true
 
 runs:
-  using: 'composite'
+  using: "composite"
   steps:
     # ————————————————————————————————————————————————————————————————
     # Checkout code, set up Go, and cache dependencies
@@ -59,7 +59,7 @@ runs:
     # ────────────────────────────────────────────────────────────────────────────
     - name: 💾 Restore Go module cache (shared)
       id: gomod-cache
-      uses: actions/cache@5a3ec84eff668545956fd18022155c47e93e2684     # v4.2.3
+      uses: actions/cache@5a3ec84eff668545956fd18022155c47e93e2684 # v4.2.3
       with:
         path: |
           ~/go/pkg/mod
@@ -133,7 +133,7 @@ runs:
     # ────────────────────────────────────────────────────────────────────────────
     - name: 💾 Restore Go build cache (per-version)
       id: gobuild-cache
-      uses: actions/cache@5a3ec84eff668545956fd18022155c47e93e2684     # v4.2.3
+      uses: actions/cache@5a3ec84eff668545956fd18022155c47e93e2684 # v4.2.3
       with:
         path: |
           ~/.cache/go-build

.github/dependabot.yml

@@ -47,10 +47,10 @@ updates:
           - "*auth*"
           - "*jwt*"
           - "*oauth*"
-        update-types: [ "minor", "patch" ]
+        update-types: ["minor", "patch"]
     open-pull-requests-limit: 10
-    assignees: [ "galt-tr","mrz1836" ]
-    labels: [ "chore", "dependencies", "gomod" ]
+    assignees: ["galt-tr", "mrz1836"]
+    labels: ["chore", "dependencies", "gomod"]
     commit-message:
       prefix: "chore"
       include: "scope"
@@ -70,10 +70,10 @@ updates:
       - dependency-type: "direct"
     groups:
       ghactions-all:
-        patterns: [ "*" ]
+        patterns: ["*"]
     open-pull-requests-limit: 10
-    assignees: [ "galt-tr","mrz1836" ]
-    labels: [ "chore", "dependencies", "github-actions" ]
+    assignees: ["galt-tr", "mrz1836"]
+    labels: ["chore", "dependencies", "github-actions"]
     commit-message:
       prefix: "chore"
       include: "scope"
@@ -93,10 +93,10 @@ updates:
       - dependency-type: "direct"
     groups:
       devcontainer-all:
-        patterns: [ "*" ]
+        patterns: ["*"]
     open-pull-requests-limit: 5
-    assignees: [ "galt-tr","mrz1836" ]
-    labels: [ "chore", "dependencies", "devcontainer" ]
+    assignees: ["galt-tr", "mrz1836"]
+    labels: ["chore", "dependencies", "devcontainer"]
     commit-message:
       prefix: "chore"
       include: "scope"