chore(version): add initial version file

- Introduces a version file to track the project's version - Sets the initial version to 0.1.0
feat(workflows): add automated changelog and release workflow
2025-05-08 19:03:42 +02:00 · 2025-05-08 19:03:30 +02:00 · 2025-05-08 19:03:18 +02:00 · 2025-05-08 19:02:24 +02:00 · 2025-05-08 19:02:14 +02:00 · 2025-05-08 19:01:55 +02:00
20 changed files with 634 additions and 68 deletions
--- a/.gitea/HOWTO_RELEASE.md
+++ b/.gitea/HOWTO_RELEASE.md
@@ -0,0 +1,124 @@
+# 📦 HOWTO: Release erstellen mit Auto-Changelog-Workflow
+
+Dieses Repository nutzt einen automatisierten CI/CD-Workflow zur **Versionsverwaltung, Changelog-Generierung und Release-Erstellung**.  
+Der gesamte Prozess ist deklarativ und läuft automatisch – ausgelöst durch Änderungen an einer Datei: `VERSION`.
+
+---
+
+## 🧭 Was passiert automatisch?
+
+Sobald Änderungen in `main` landen, prüft der Workflow:
+
+- 🔍 **Hat sich die Datei `VERSION` geändert?**
+  - ❌ **Nein** → es wird nur das `CHANGELOG.md` aktualisiert (unreleased Abschnitt)
+  - ✅ **Ja** → es wird:
+    - ein vollständiger Changelog für diese Version erzeugt
+    - ein Git-Tag `vX.Y.Z` erstellt
+    - ein Release in Gitea veröffentlicht (inkl. Beschreibung aus dem Changelog)
+
+---
+
+## ✅ Wie erzeuge ich ein Release?
+
+### 1. Erhöhe die Version in der Datei `VERSION`
+
+Beispiel:
+
+```txt
+1.2.3
+```
+
+> Diese Datei muss **als eigene Commit-Änderung** erfolgen – idealerweise als letzter Commit in einem PR.
+> Die Commit-Nachricht sollte mit `chore(version)` beginnen, damit dieser nicht im Changelog auftaucht.
+
+---
+
+### 2. Mergen in `main`
+
+Sobald `main` den Commit mit neuer `VERSION` enthält, wird automatisch:
+
+- das `CHANGELOG.md` regeneriert und committed
+- der neue Git-Tag erstellt (`v1.2.3`)
+- ein Gitea Release mit genau diesem Changelog erzeugt
+
+---
+
+## 🛡️ Hinweis zu Tokens & Webhooks
+
+Damit das Release auch korrekt weitere Workflows auslösen kann (z. B. über `on: release`), ist **ein Personal Access Token notwendig**.
+
+### 🔐 Secret: `RELEASE_PUBLISH_TOKEN`
+
+> Lege ein Repository-Secret mit diesem Namen an.  
+> Es sollte ein **Gitea Personal Access Token** mit folgenden Berechtigungen sein:
+
+- `write:repo`
+- `write:release`
+- idealerweise: keine Ablaufzeit
+
+Wird dieser Token **nicht** gesetzt, fällt der Workflow auf `ACTIONS_RUNTIME_TOKEN` zurück, aber:
+- Release wird trotzdem erstellt
+- **⚠️ andere Workflows, die auf `release.published` reagieren, könnten nicht getriggert werden**
+
+---
+
+## 🧪 Debugging-Tipps
+
+- Stelle sicher, dass `VERSION` exakt **eine gültige neue semver-Version** enthält
+- Achte auf den Commit-Log: Changelog-Commits sind mit `chore(changelog):` gekennzeichnet
+- Verwende nur `main` als Trigger-Zweig
+
+---
+
+## 🧩 Erweiterung
+
+In `upload-assets.yml` kannst du beliebige Build-Artefakte automatisch an das Release anhängen, sobald es veröffentlicht ist.
+
+Dafür:
+- liegt das Script `.gitea/scripts/get-release-id.sh`
+- sowie `.gitea/scripts/upload-asset.sh` bereit
+
+Mehr dazu in der Datei: `.gitea/workflows/upload-assets.yml`
+
+---
+
+## 🧘 Best Practice
+
+- Changelog-Generierung nie manuell ausführen
+- Nur `VERSION` ändern, um ein neues Release auszulösen
+- Auf `CHANGELOG.md` nie direkt committen
+- Release-Daten niemals per Hand in Gitea pflegen
+
+📎 Alles wird versioniert, automatisiert und reproduzierbar erzeugt.
+
+---
+
+## 🧠 Commit-Gruppierung & Changelog-Erzeugung
+
+Der Changelog wird auf Basis definierter **Commit-Gruppen** erzeugt.  
+Diese Regeln sind in `cliff.toml` unter `commit_parsers` konfiguriert.
+
+| Prefix / Muster                | Gruppe                    | Beschreibung                                     |
+|-------------------------------|---------------------------|--------------------------------------------------|
+| `feat:`                       | 🚀 Features               | Neue Funktionalität                              |
+| `fix:`                        | 🐛 Bug Fixes              | Fehlerbehebungen                                 |
+| `doc:`                        | 📚 Documentation          | Änderungen an Doku, Readmes etc.                 |
+| `perf:`                       | ⚡ Performance             | Leistungsverbesserungen                          |
+| `refactor:`                   | 🚜 Refactor               | Reorganisation ohne Verhaltensänderung           |
+| `style:`                      | 🎨 Styling                | Formatierung, Whitespaces, Code-Style            |
+| `test:`                       | 🧪 Testing                | Neue oder angepasste Tests                       |
+| `ci:` oder `chore:` (ohne Spezifizierung) | ⚙️ Miscellaneous Tasks | CI-Änderungen, Aufgaben, Wartung etc.            |
+| `chore(changelog)`, `chore(version)`, `chore(release): prepare for`, `chore(deps...)`, `chore(pr)`, `chore(pull)` | *(ignoriert)* | Diese Commits werden im Changelog **ausgelassen** |
+| Commit-Body enthält `security` | 🛡️ Security              | Sicherheitsrelevante Änderungen                  |
+| `revert:`                     | ◀️ Revert                | Rückgängig gemachte Commits                      |
+| alles andere                  | 💼 Other                 | Fallback für nicht erkannte Formate              |
+
+### ✍️ Beispiel:
+
+```bash
+git commit -m "feat: add login endpoint"
+git commit -m "fix: prevent crash on null input"
+git commit -m "chore(version): bump to 1.2.3"
+```
+
+> Nur die ersten beiden erscheinen im Changelog – der dritte wird **automatisch übersprungen**.
--- a/.gitea/scripts/get-release-id.sh
+++ b/.gitea/scripts/get-release-id.sh
@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Eingaben
+TAG="$1"
+TOKEN="${ACTIONS_RUNTIME_TOKEN:-<fallback_token>}"
+REPO="${GITHUB_REPOSITORY:-owner/example}"
+API="${GITHUB_API_URL:-https://gitea.example.tld/api/v1}"
+
+OWNER=$(echo "$REPO" | cut -d/ -f1)
+NAME=$(echo "$REPO" | cut -d/ -f2)
+
+RESPONSE=$(curl -sf \
+  -H "Authorization: token $TOKEN" \
+  "$API/repos/$OWNER/$NAME/releases/tags/$TAG")
+
+RELEASE_ID=$(echo "$RESPONSE" | jq -r '.id')
+echo "Release-ID für $TAG ist: $RELEASE_ID"
+
+# Für GitHub Actions als Umgebungsvariable
+echo "GT_RELEASE_ID=$RELEASE_ID" >> "$GITHUB_ENV"
--- a/.gitea/scripts/upload-asset.sh
+++ b/.gitea/scripts/upload-asset.sh
@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Eingabeparameter
+FILE_PATH="$1"                      # z. B. ./dist/build.zip
+CUSTOM_NAME="${2:-}"               # optional: anderer Name unter dem das Asset gespeichert werden soll
+RELEASE_ID="${GT_RELEASE_ID:-}"       # aus Umgebung
+
+# Validierung
+if [[ -z "$RELEASE_ID" ]]; then
+  echo "❌ RELEASE_ID ist nicht gesetzt. Abbruch."
+  exit 1
+fi
+
+if [[ ! -f "$FILE_PATH" ]]; then
+  echo "❌ Datei '$FILE_PATH' existiert nicht. Abbruch."
+  exit 1
+fi
+
+# Default-Konfiguration
+TOKEN="${ACTIONS_RUNTIME_TOKEN:-<fallback_token>}"
+REPO="${GITHUB_REPOSITORY:-owner/example}"
+API="${GITHUB_API_URL:-https://gitea.example.tld/api/v1}"
+
+# Owner/Repo auflösen
+OWNER=$(echo "$REPO" | cut -d/ -f1)
+NAME=$(echo "$REPO" | cut -d/ -f2)
+
+# Dateiname setzen
+FILENAME="${CUSTOM_NAME:-$(basename "$FILE_PATH")}"
+
+echo "🔼 Uploading '$FILE_PATH' as '$FILENAME' to release ID $RELEASE_ID"
+
+# Upload
+curl -sf -X POST \
+  -H "Authorization: token $TOKEN" \
+  -F "attachment=@$FILE_PATH" \
+  "$API/repos/$OWNER/$NAME/releases/$RELEASE_ID/assets?name=$FILENAME"
+
+echo "✅ Upload abgeschlossen: $FILENAME"
--- a/.gitea/workflows/release.yml
+++ b/.gitea/workflows/release.yml
@@ -0,0 +1,211 @@
+name: Auto Changelog & Release
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+
+jobs:
+  detect-version-change:
+    runs-on: ubuntu-latest
+    outputs:
+      version_changed: ${{ steps.check.outputs.version_changed }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Check if VERSION file changed
+        id: check
+        run: |
+          echo "🔍 Vergleich mit github.event.before:"
+          echo "Before: ${{ github.event.before }}"
+          echo "After:  ${{ github.sha }}"
+          
+          echo "📄 Changed files between before and after:"
+          git diff --name-only ${{ github.event.before }} ${{ github.sha }} || echo "(diff failed)"
+
+          if git diff --name-only ${{ github.event.before }} ${{ github.sha }} | grep -q '^VERSION$'; then
+            echo "✅ VERSION file was changed between before and after"
+            echo "version_changed=true" >> $GITHUB_OUTPUT
+          else
+            echo "ℹ️ VERSION file not changed between before and after"
+            echo "version_changed=false" >> $GITHUB_OUTPUT
+          fi
+
+  changelog-only:
+    needs: detect-version-change
+    if: needs.detect-version-change.outputs.version_changed == 'false'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set Git Author
+        run: |
+          git config user.name "$CI_COMMIT_AUTHOR_NAME"
+          git config user.email "$CI_COMMIT_AUTHOR_EMAIL"
+
+      - name: Read CLIFF_VERSION from cliff.toml
+        id: cliff_version
+        run: |
+          echo "version=$(awk -F '=' '/^# CLIFF_VERSION=/ { gsub(/[" ]/, "", $2); print $2 }' cliff.toml)" >> $GITHUB_OUTPUT
+
+      - name: Restore git-cliff cache
+        id: restore-cliff
+        uses: https://git.0xmax42.io/actions/cache@v1
+        with:
+          key: cargo-cliff-${{ steps.cliff_version.outputs.version }}
+          paths: |
+            /root/.cargo/bin
+
+      - name: Install git-cliff
+        if: steps.restore-cliff.outputs.cache-hit != 'true'
+        run: |
+          cargo install git-cliff --version "${{ steps.cliff_version.outputs.version }}" --features gitea
+
+      - name: Generate unreleased changelog
+        run: git-cliff -c cliff.toml -o CHANGELOG.md
+
+      - name: Commit updated CHANGELOG.md
+        run: |
+          git add CHANGELOG.md
+          if git diff --cached --quiet; then
+            echo "No changes to commit"
+          else
+            git commit -m "chore(changelog): update unreleased changelog"
+            git push origin main
+          fi
+
+  release:
+    needs: detect-version-change
+    if: needs.detect-version-change.outputs.version_changed == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set Git Author
+        run: |
+          git config user.name "$CI_COMMIT_AUTHOR_NAME"
+          git config user.email "$CI_COMMIT_AUTHOR_EMAIL"
+
+      - name: Read VERSION
+        id: version
+        run: echo "value=$(cat VERSION)" >> $GITHUB_OUTPUT
+
+      - name: Read CLIFF_VERSION from cliff.toml
+        id: cliff_version
+        run: |
+          echo "version=$(awk -F '=' '/^# CLIFF_VERSION=/ { gsub(/[" ]/, "", $2); print $2 }' cliff.toml)" >> $GITHUB_OUTPUT
+
+      - name: Restore git-cliff cache
+        id: restore-cliff
+        uses: https://git.0xmax42.io/actions/cache@v1
+        with:
+          key: cargo-cliff-${{ steps.cliff_version.outputs.version }}
+          paths: |
+            /root/.cargo/bin
+
+      - name: Install git-cliff
+        if: steps.restore-cliff.outputs.cache-hit != 'true'
+        run: |
+          cargo install git-cliff --version "${{ steps.cliff_version.outputs.version }}" --features gitea
+      
+      - name: Generate changelog for release and tag
+        id: generate-changelog
+        run: |
+          VERSION=${{ steps.version.outputs.value }}
+          git-cliff -c cliff.toml -t "v$VERSION" -o CHANGELOG.md
+
+          BODY=$(mktemp)
+          ESCAPED_VERSION=$(echo "$VERSION" | sed 's/\./\\./g')
+
+          awk -v ver="$ESCAPED_VERSION" '
+            $0 ~ "^## \\[" ver "\\]" {
+              print_flag=1
+              line = $0
+              sub(/^## /, "", line)
+              sub(/\\s*\\(.*\\)/, "", line)  # entfernt z. B. "(...)" oder "(*)"
+              print line
+              next
+            }
+            $0 ~ "^## \\[" && $0 !~ "^## \\[" ver "\\]" {
+              print_flag=0
+            }
+            print_flag
+          ' CHANGELOG.md > "$BODY"
+
+          echo "changelog_body_path=$BODY" >> $GITHUB_OUTPUT
+
+
+      - name: Commit updated CHANGELOG.md
+        run: |
+          git add CHANGELOG.md
+          if git diff --cached --quiet; then
+            echo "No changes to commit"
+          else
+            git commit -m "chore(changelog): update changelog for v${{ steps.version.outputs.value }}"
+            git push origin main
+          fi
+
+      - name: Create Git tag (if not exists)
+        run: |
+          VERSION=${{ steps.version.outputs.value }}
+          if git rev-parse "v$VERSION" >/dev/null 2>&1; then
+            echo "Tag v$VERSION already exists, skipping tag creation."
+          else
+            git tag -a "v$VERSION" -F "${{ steps.generate-changelog.outputs.changelog_body_path }}" --cleanup=verbatim
+            git push origin "v$VERSION"
+          fi
+
+      - name: Create Gitea release
+        env: 
+          RELEASE_PUBLISH_TOKEN: ${{ secrets.RELEASE_PUBLISH_TOKEN }}
+        run: |
+          VERSION=${{ steps.version.outputs.value }}
+          BODY_FILE="${{ steps.generate-changelog.outputs.changelog_body_path }}"
+
+          OWNER=$(echo "$GITHUB_REPOSITORY" | cut -d/ -f1)
+          REPO=$(echo "$GITHUB_REPOSITORY" | cut -d/ -f2)
+
+          # Token-Auswahl
+          TOKEN="${RELEASE_PUBLISH_TOKEN:-$ACTIONS_RUNTIME_TOKEN}"
+
+          if [[ -z "${RELEASE_PUBLISH_TOKEN:-}" ]]; then
+            echo "::warning title=Limited Release Propagation::"
+            echo "RELEASE_PUBLISH_TOKEN is not set. Using ACTIONS_RUNTIME_TOKEN instead."
+            echo "⚠️  Release events may not trigger other workflows if created with the runtime token."
+            echo
+          fi
+
+          # Prüfe, ob der Release schon existiert
+          if curl -sf "$GITHUB_API_URL/repos/$OWNER/$REPO/releases/tags/v$VERSION" \
+            -H "Authorization: token $TOKEN" > /dev/null; then
+            echo "🔁 Release for tag v$VERSION already exists, skipping."
+            exit 0
+          fi
+
+          echo "🚀 Creating Gitea release for v$VERSION"
+
+          # Release-Beschreibung vorbereiten
+          RELEASE_BODY=$(tail -n +2 "$BODY_FILE" | jq -Rs .)
+
+          curl -X POST "$GITHUB_API_URL/repos/$OWNER/$REPO/releases" \
+            -H "Authorization: token $TOKEN" \
+            -H "Content-Type: application/json" \
+            -d @- <<EOF
+          {
+            "tag_name": "v$VERSION",
+            "target_commitish": "main",
+            "name": "Release v$VERSION",
+            "body": $RELEASE_BODY,
+            "draft": false,
+            "prerelease": false
+          }
+          EOF
+
+          echo "✅ Release for tag $VERSION created successfully."
--- a/.gitea/workflows/upload-assets.yml.example
+++ b/.gitea/workflows/upload-assets.yml.example
@@ -0,0 +1,47 @@
+# ========================
+# 📦 Upload Assets Template
+# ========================
+# Dieser Workflow wird automatisch ausgelöst, wenn ein Release
+# in Gitea veröffentlicht wurde (event: release.published).
+#
+# Er dient dem Zweck, Release-Artefakte (wie z. B. Binary-Dateien,
+# Changelogs oder Build-Zips) nachträglich mit dem Release zu verknüpfen.
+#
+# Voraussetzung: Zwei Shell-Skripte liegen im Projekt:
+# - .gitea/scripts/get-release-id.sh → ermittelt Release-ID per Tag
+# - .gitea/scripts/upload-asset.sh → lädt Datei als Release-Asset hoch
+#
+# --------------------------------------
+
+name: Upload Assets
+
+on:
+  release:
+    types: [published]  # Nur bei Veröffentlichung eines Releases (nicht bei Entwürfen)
+
+jobs:
+  upload-assets:
+    runs-on: ubuntu-latest
+
+    steps:
+      # 📥 Checke den Stand des Repos aus, exakt auf dem veröffentlichten Tag
+      # So ist garantiert, dass die Artefakte dem Zustand des Releases entsprechen.
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.release.tag_name }}  # z. B. "v1.2.3"
+          fetch-depth: 0                             # vollständige Git-Historie (für z. B. git-cliff, logs etc.)
+
+      # 🆔 Hole die Release-ID basierend auf dem Tag
+      # Die ID wird als Umgebungsvariable RELEASE_ID über $GITHUB_ENV verfügbar gemacht.
+      - name: Get Release ID from tag
+        run: .gitea/scripts/get-release-id.sh "${{ github.event.release.tag_name }}"
+
+      # 🔼 Upload eines Release-Assets
+      # Beispiel: Lade CHANGELOG.md als Datei mit abweichendem Namen "RELEASE-NOTES.md" hoch
+      #
+      # Du kannst beliebig viele Upload-Schritte hinzufügen oder in einer Schleife iterieren.
+      #
+      # Hinweis: RELEASE_ID wird automatisch verwendet, da get-release-id.sh sie exportiert.
+      #
+      # - name: Upload CHANGELOG.md as RELEASE-NOTES.md
+      #   run: .gitea/scripts/upload-asset.sh ./CHANGELOG.md RELEASE-NOTES.md
--- a/.gitignore
+++ b/.gitignore
@@ -6,3 +6,4 @@ cache/
 out.py
 output.txt
 git_log_diff.txt
+.gitea/COMMIT_GPT.md
--- a/.vscode/settings.json
+++ b/.vscode/settings.json
@@ -18,4 +18,13 @@
    ],
    "exportall.config.barrelName": "mod.ts",
    "exportall.config.message": "deno-coverage-ignore-file",
+    "workbench.colorCustomizations": {
+        "activityBar.activeBackground": "#9ed8bc",
+        "activityBar.background": "#9ed8bc",
+        "activityBar.foreground": "#15202b",
+        "activityBar.inactiveForeground": "#15202b99",
+        "activityBarBadge.background": "#a177c8",
+        "activityBarBadge.foreground": "#15202b"
+    },
+    "peacock.color": "#7ac9a3",
 }
--- a/1
+++ b/1
@@ -0,0 +1 @@
+0.1.0
--- a/cliff.toml
+++ b/cliff.toml
@@ -0,0 +1,104 @@
+# CLIFF_VERSION=2.8.0
+# git-cliff ~ default configuration file
+# https://git-cliff.org/docs/configuration
+#
+# Lines starting with "#" are comments.
+# Configuration options are organized into tables and keys.
+# See documentation for more information on available options.
+[remote.gitea]
+owner = "maxp"
+repo = "http-kernel"
+
+[changelog]
+# postprocessors
+postprocessors = [
+  { pattern = '<GITEA_URL>', replace = "https://git.0xmax42.io" }, # replace gitea url
+]
+
+# template for the changelog header
+header = """
+# Changelog\n
+All notable changes to this project will be documented in this file.\n
+"""
+# template for the changelog body
+# https://keats.github.io/tera/docs/#introduction
+body = """
+{%- macro remote_url() -%}
+  <GITEA_URL>/{{ remote.gitea.owner }}/{{ remote.gitea.repo }}
+{%- endmacro -%}
+
+{% if version %}\
+    {% if previous.version %}\
+        ## [{{ version | trim_start_matches(pat="v") }}]\
+          ({{ self::remote_url() }}/compare/{{ previous.version }}..{{ version }}) - {{ timestamp | date(format="%Y-%m-%d") }}
+    {% else %}\
+        ## [{{ version | trim_start_matches(pat="v") }}] - {{ timestamp | date(format="%Y-%m-%d") }}
+    {% endif %}\
+{% else %}\
+    ## [unreleased]
+{% endif %}\
+{% for group, commits in commits | group_by(attribute="group") %}
+    ### {{ group | striptags | trim | upper_first }}
+    {% for commit in commits %}
+        - {% if commit.scope %}*({{ commit.scope }})* {% endif %}\
+            {% if commit.breaking %}[**breaking**] {% endif %}\
+            {{ commit.message | upper_first }} - \
+            ([{{ commit.id | truncate(length=7, end="") }}]({{ self::remote_url() }}/commit/{{ commit.id }}))\
+    {% endfor %}
+{% endfor %}\n
+"""
+# template for the changelog footer
+footer = """
+
+"""
+# remove the leading and trailing s
+trim = true
+
+# render body even when there are no releases to process
+# render_always = true
+# output file path
+# output = "test.md"
+
+[git]
+# parse the commits based on https://www.conventionalcommits.org
+conventional_commits = true
+# filter out the commits that are not conventional
+filter_unconventional = true
+# process each line of a commit as an individual commit
+split_commits = false
+# regex for preprocessing the commit messages
+commit_preprocessors = [
+  # Replace issue numbers
+  #{ pattern = '\((\w+\s)?#([0-9]+)\)', replace = "([#${2}](<REPO>/issues/${2}))"},
+  # Check spelling of the commit with https://github.com/crate-ci/typos
+  # If the spelling is incorrect, it will be automatically fixed.
+  #{ pattern = '.*', replace_command = 'typos --write-changes -' },
+]
+# regex for parsing and grouping commits
+commit_parsers = [
+  { message = "^feat", group = "<!-- 0 -->🚀 Features" },
+  { message = "^fix", group = "<!-- 1 -->🐛 Bug Fixes" },
+  { message = "^doc", group = "<!-- 3 -->📚 Documentation" },
+  { message = "^perf", group = "<!-- 4 -->⚡ Performance" },
+  { message = "^refactor", group = "<!-- 2 -->🚜 Refactor" },
+  { message = "^style", group = "<!-- 5 -->🎨 Styling" },
+  { message = "^test", group = "<!-- 6 -->🧪 Testing" },
+  { message = "^chore\\(changelog\\)", skip = true },
+  { message = "^chore\\(version\\)", skip = true },
+  { message = "^chore\\(release\\): prepare for", skip = true },
+  { message = "^chore\\(deps.*\\)", skip = true },
+  { message = "^chore\\(pr\\)", skip = true },
+  { message = "^chore\\(pull\\)", skip = true },
+  { message = "^chore|^ci", group = "<!-- 7 -->⚙️ Miscellaneous Tasks" },
+  { body = ".*security", group = "<!-- 8 -->🛡️ Security" },
+  { message = "^revert", group = "<!-- 9 -->◀️ Revert" },
+  { message = ".*", group = "<!-- 10 -->💼 Other" },
+]
+# Regex to select git tags that represent releases.
+tag_pattern = "v[0-9]+\\.[0-9]+\\.[0-9]+"
+# filter out the commits that are not matched by commit parsers
+filter_commits = false
+# sort the tags topologically
+topo_order = false
+# sort the commits inside sections by oldest/newest order
+sort_commits = "newest"
--- a/deno.jsonc
+++ b/deno.jsonc
@@ -1,8 +1,11 @@
 {
+    "name": "@0xmax42/http-kernel",
+    "description": "A simple HTTP kernel for Deno",
    "tasks": {
        // "start": "deno run --allow-net --allow-env --unstable-kv --allow-read --allow-write --env-file src/main.ts -- --verbose",
        // "watch": "deno run --watch --allow-net --allow-env --unstable-kv --allow-read --allow-write --env-file src/main.ts -- --verbose",
-        "test": "deno test --allow-net --allow-env --unstable-kv --allow-read --allow-write --coverage **/__tests__/*.test.ts"
+        "test": "deno test --allow-net --allow-env --unstable-kv --allow-read --allow-write --coverage **/__tests__/*.test.ts",
+        "test:watch": "deno test --watch --allow-net --allow-env --unstable-kv --allow-read --allow-write **/__tests__/*.test.ts"
    },
    "compilerOptions": {
        "lib": [
@@ -24,6 +27,6 @@
            "src/",
            "main.ts"
        ]
-    },
+    }
    //"importMap": "./import_map.json"
 }
--- a/src/HttpKernel.ts
+++ b/src/HttpKernel.ts
@@ -1,20 +1,20 @@
 import {
    IContext,
-    IHandler,
    IHttpKernel,
    IHttpKernelConfig,
    IInternalRoute,
-    IMiddleware,
    IRouteBuilder,
    IRouteDefinition,
-    isHandler,
-    isMiddleware,
 } from './Interfaces/mod.ts';
 import {
    DeepPartial,
+    Handler,
    HTTP_404_NOT_FOUND,
    HTTP_500_INTERNAL_SERVER_ERROR,
    HttpStatusTextMap,
+    isHandler,
+    isMiddleware,
+    Middleware,
 } from './Types/mod.ts';
 import { RouteBuilder } from './RouteBuilder.ts';
 import { createEmptyContext, normalizeError } from './Utils/mod.ts';
@@ -151,8 +151,8 @@ export class HttpKernel<TContext extends IContext = IContext>
     */
    private async executePipeline(
        ctx: TContext,
-        middleware: IMiddleware<TContext>[],
-        handler: IHandler<TContext>,
+        middleware: Middleware<TContext>[],
+        handler: Handler<TContext>,
    ): Promise<Response> {
        const handleInternalError = (ctx: TContext, err?: unknown) =>
            this.cfg.httpErrorHandlers[HTTP_500_INTERNAL_SERVER_ERROR](
--- a/src/Interfaces/IInternalRoute.ts
+++ b/src/Interfaces/IInternalRoute.ts
@@ -1,6 +1,4 @@
-import { HttpMethod } from '../Types/mod.ts';
-import { IHandler } from './IHandler.ts';
-import { IMiddleware } from './IMiddleware.ts';
+import { Handler, HttpMethod, Middleware } from '../Types/mod.ts';
 import { IContext, IRouteMatcher } from './mod.ts';

 /**
@@ -32,10 +30,10 @@ export interface IInternalRoute<TContext extends IContext = IContext> {
    /**
     * An ordered list of middleware functions to be executed before the handler.
     */
-    middlewares: IMiddleware<TContext>[];
+    middlewares: Middleware<TContext>[];

    /**
     * The final handler that generates the HTTP response after all middleware has run.
     */
-    handler: IHandler<TContext>;
+    handler: Handler<TContext>;
 }
--- a/src/Interfaces/IRouteBuilder.ts
+++ b/src/Interfaces/IRouteBuilder.ts
@@ -1,6 +1,5 @@
-import { IHandler } from './IHandler.ts';
+import { Handler, Middleware } from '../Types/mod.ts';
 import { IInternalRoute } from './IInternalRoute.ts';
-import { IMiddleware } from './IMiddleware.ts';
 import { IRouteDefinition } from './IRouteDefinition.ts';
 import { IContext } from './mod.ts';

@@ -8,7 +7,7 @@ export interface IRouteBuilderFactory<TContext extends IContext = IContext> {
    new (
        registerRoute: (route: IInternalRoute<TContext>) => void,
        def: IRouteDefinition,
-        mws?: IMiddleware<TContext>[],
+        mws?: Middleware<TContext>[],
    ): IRouteBuilder<TContext>;
 }

@@ -25,7 +24,7 @@ export interface IRouteBuilder<TContext extends IContext = IContext> {
     * @returns The route builder for further chaining.
     */
    middleware(
-        mw: IMiddleware<TContext>,
+        mw: Middleware<TContext>,
    ): IRouteBuilder<TContext>;

    /**
@@ -35,6 +34,6 @@ export interface IRouteBuilder<TContext extends IContext = IContext> {
     * @param handler - The function to execute when this route is matched.
     */
    handle(
-        handler: IHandler<TContext>,
+        handler: Handler<TContext>,
    ): void;
 }
--- a/src/Interfaces/mod.ts
+++ b/src/Interfaces/mod.ts
@@ -1,14 +1,10 @@
 // deno-coverage-ignore-file

 export type { IContext } from './IContext.ts';
-export { isHandler } from './IHandler.ts';
-export type { IHandler } from './IHandler.ts';
 export type { IHttpErrorHandlers } from './IHttpErrorHandlers.ts';
 export type { IHttpKernel } from './IHttpKernel.ts';
 export type { IHttpKernelConfig } from './IHttpKernelConfig.ts';
 export type { IInternalRoute } from './IInternalRoute.ts';
-export { isMiddleware } from './IMiddleware.ts';
-export type { IMiddleware } from './IMiddleware.ts';
 export type { IRouteBuilder, IRouteBuilderFactory } from './IRouteBuilder.ts';
 export {
    isDynamicRouteDefinition,
--- a/src/RouteBuilder.ts
+++ b/src/RouteBuilder.ts
@@ -1,12 +1,6 @@
 import { IRouteMatcherFactory } from './Interfaces/IRouteMatcher.ts';
-import {
-    IContext,
-    IHandler,
-    IMiddleware,
-    IRouteBuilder,
-    IRouteDefinition,
-} from './Interfaces/mod.ts';
-import { RegisterRoute } from './Types/mod.ts';
+import { IContext, IRouteBuilder, IRouteDefinition } from './Interfaces/mod.ts';
+import { Handler, Middleware, RegisterRoute } from './Types/mod.ts';
 import { createRouteMatcher } from './Utils/createRouteMatcher.ts';

 /**
@@ -27,7 +21,7 @@ export class RouteBuilder<TContext extends IContext = IContext>
    constructor(
        private readonly registerRoute: RegisterRoute<TContext>,
        private readonly def: IRouteDefinition,
-        private readonly mws: IMiddleware<TContext>[] = [],
+        private readonly mws: Middleware<TContext>[] = [],
        private readonly matcherFactory: IRouteMatcherFactory =
            createRouteMatcher,
    ) {}
@@ -42,7 +36,7 @@ export class RouteBuilder<TContext extends IContext = IContext>
     * @returns A new `RouteBuilder` instance for continued chaining.
     */
    middleware(
-        mw: IMiddleware<TContext>,
+        mw: Middleware<TContext>,
    ): IRouteBuilder<TContext> {
        return new RouteBuilder<TContext>(
            this.registerRoute,
@@ -60,7 +54,7 @@ export class RouteBuilder<TContext extends IContext = IContext>
     * @param handler - The final request handler for this route.
     */
    handle(
-        handler: IHandler<TContext>,
+        handler: Handler<TContext>,
    ): void {
        const matcher = this.matcherFactory(this.def);
        this.registerRoute({
--- a/src/Interfaces/IHandler.ts
+++ b/src/Interfaces/IHandler.ts
@@ -1,4 +1,4 @@
-import { IContext } from './IContext.ts';
+import { IContext } from '../Interfaces/mod.ts';

 /**
 * Represents a final request handler responsible for producing an HTTP response.
@@ -11,16 +11,23 @@ import { IContext } from './IContext.ts';
 *
 * @template TContext The specific context type for this handler, including typed `state`, `params`, and `query`.
 */
-export interface IHandler<TContext extends IContext = IContext> {
+type Handler<TContext extends IContext = IContext> = (
+    ctx: TContext,
+) => Promise<Response>;
+
 /**
-     * Handles the request and generates a response.
+ * Represents a handler function with an associated name.
 *
-     * @param ctx - The complete request context, including request metadata, route and query parameters,
-     *              and mutable state populated during the middleware phase.
-     * @returns A `Promise` resolving to an HTTP `Response` to be sent to the client.
+ * This is useful for debugging, logging, or when you need to reference
+ * the handler by name in your application.
+ *
+ * @template TContext The specific context type for this handler, including typed `state`, `params`, and `query`.
 */
-    (ctx: TContext): Promise<Response>;
-}
+type NamedHandler<TContext extends IContext = IContext> =
+    & Handler<TContext>
+    & { name?: string };
+
+export type { NamedHandler as Handler };

 /**
 * Type guard to determine whether a given value is a valid `IHandler` function.
@@ -42,7 +49,7 @@ export interface IHandler<TContext extends IContext = IContext> {
 */
 export function isHandler<TContext extends IContext = IContext>(
    value: unknown,
-): value is IHandler<TContext> {
+): value is Handler<TContext> {
    return (
        typeof value === 'function' &&
        value.length === 1 // ctx
--- a/src/Interfaces/IMiddleware.ts
+++ b/src/Interfaces/IMiddleware.ts
@@ -1,4 +1,4 @@
-import { IContext } from './IContext.ts';
+import { IContext } from '../Interfaces/IContext.ts';

 /**
 * Represents a middleware function in the HTTP request pipeline.
@@ -13,16 +13,24 @@ import { IContext } from './IContext.ts';
 *
 * @template TContext The specific context type for this middleware, including state, params, and query information.
 */
-export interface IMiddleware<TContext extends IContext = IContext> {
+type Middleware<TContext extends IContext = IContext> = (
+    ctx: TContext,
+    next: () => Promise<Response>,
+) => Promise<Response>;
+
 /**
-     * Handles the request processing at this middleware stage.
+ * Represents a middleware function with an associated name.
 *
-     * @param ctx - The full request context, containing request, params, query, and typed state.
-     * @param next - A continuation function that executes the next middleware or handler in the pipeline.
-     * @returns A `Promise` resolving to an HTTP `Response`, either from this middleware or downstream.
+ * This is useful for debugging, logging, or when you need to reference
+ * the middleware by name in your application.
+ *
+ * @template TContext The specific context type for this middleware, including state, params, and query information.
 */
-    (ctx: TContext, next: () => Promise<Response>): Promise<Response>;
-}
+type NamedMiddleware<TContext extends IContext = IContext> =
+    & Middleware<TContext>
+    & { name?: string };
+
+export type { NamedMiddleware as Middleware };

 /**
 * Type guard to verify whether a given value is a valid `IMiddleware` function.
@@ -35,7 +43,7 @@ export interface IMiddleware<TContext extends IContext = IContext> {
 */
 export function isMiddleware<TContext extends IContext = IContext>(
    value: unknown,
-): value is IMiddleware<TContext> {
+): value is Middleware<TContext> {
    return (
        typeof value === 'function' &&
        value.length === 2 // ctx, next
--- a/src/Types/mod.ts
+++ b/src/Types/mod.ts
@@ -1,6 +1,8 @@
 // deno-coverage-ignore-file

 export type { DeepPartial } from './DeepPartial.ts';
+export { isHandler } from './Handler.ts';
+export type { Handler } from './Handler.ts';
 export type { HttpErrorHandler } from './HttpErrorHandler.ts';
 export { isHttpMethod, validHttpMethods } from './HttpMethod.ts';
 export type { HttpMethod } from './HttpMethod.ts';
@@ -34,6 +36,8 @@ export {
    validHttpStatusCodes,
 } from './HttpStatusCode.ts';
 export type { HttpStatusCode } from './HttpStatusCode.ts';
+export { isMiddleware } from './Middleware.ts';
+export type { Middleware } from './Middleware.ts';
 export type { Params } from './Params.ts';
 export type { Query } from './Query.ts';
 export type { RegisterRoute } from './RegisterRoute.ts';
--- a/src/Utils/createRouteMatcher.ts
+++ b/src/Utils/createRouteMatcher.ts
@@ -35,7 +35,9 @@ export function createRouteMatcher(
        // 3b. Extract route params
        const params: Params = {};
        for (const [key, value] of Object.entries(result.pathname.groups)) {
-            params[key] = value ?? ''; // null → empty string
+            if (value) {
+                params[key] = value;
+            }
        }

        // 3c. Extract query parameters – keep duplicates as arrays
--- a/src/tests/RouteBuilder.test.ts
+++ b/src/tests/RouteBuilder.test.ts
@@ -4,17 +4,14 @@ import {
    assertNotEquals,
    assertThrows,
 } from 'https://deno.land/std@0.204.0/assert/mod.ts';
-import {
-    IHandler,
-    IInternalRoute,
-    IMiddleware,
-    IRouteDefinition,
-} from '../Interfaces/mod.ts';
+import { IInternalRoute, IRouteDefinition } from '../Interfaces/mod.ts';
 import { RouteBuilder } from '../mod.ts';
+import { Handler, Middleware } from '../Types/mod.ts';

 // Dummy objects
-const dummyHandler: IHandler = async () => new Response('ok');
-const dummyMiddleware: IMiddleware = async (_, next) => await next();
+// deno-lint-ignore require-await
+const dummyHandler: Handler = async () => new Response('ok');
+const dummyMiddleware: Middleware = async (_, next) => await next();
 const dummyDef: IRouteDefinition = { method: 'GET', path: '/hello' };
 const dummyMatcher = () => ({ params: {} });

@@ -39,8 +36,8 @@ Deno.test('middleware: middleware is chained immutably', () => {
 });

 Deno.test('middleware: preserves order of middleware', () => {
-    const mw1: IMiddleware = async (_, next) => await next();
-    const mw2: IMiddleware = async (_, next) => await next();
+    const mw1: Middleware = async (_, next) => await next();
+    const mw2: Middleware = async (_, next) => await next();

    let result: IInternalRoute | null = null as IInternalRoute | null;
Author	SHA1	Message	Date
Max P.	3afe6bcbc3	chore(version): add initial version file All checks were successful Auto Changelog & Release / detect-version-change (push) Successful in 10s Details Auto Changelog & Release / changelog-only (push) Has been skipped Details Auto Changelog & Release / release (push) Successful in 2m21s Details - Introduces a version file to track the project's version - Sets the initial version to 0.1.0	2025-05-08 19:03:42 +02:00
Max P.	bbf78cff17	feat(workflows): add automated changelog and release workflow - Introduces a GitHub Actions workflow for automated changelog generation and release creation triggered by version changes or manual dispatch. - Includes steps for detecting version file changes, generating changelogs using git-cliff, and publishing releases to Gitea.	2025-05-08 19:03:30 +02:00
Max P.	8235680904	refactor(types): unify handler and middleware definitions - Consolidates `Handler` and `Middleware` types under `Types` module - Replaces `IHandler` and `IMiddleware` interfaces with typed functions - Simplifies imports and improves code organization - Enhances debugging with named handlers and middlewares	2025-05-08 19:03:18 +02:00
Max P.	56633cd95b	feat(vscode): customize activity bar and peacock colors - Add custom colors for the activity bar to enhance UI aesthetics - Set Peacock extension color for consistent workspace theming	2025-05-08 19:02:24 +02:00
Max P.	5c03cdfb03	docs(gitea): add release automation guide and scripts - Document automated release process with versioning and changelog generation - Add scripts for retrieving release IDs and uploading assets to releases - Provide best practices and debugging tips for maintaining consistency	2025-05-08 19:02:14 +02:00
Max P.	661f83d1fd	chore(config): add default git-cliff configuration - Introduces a default configuration file for git-cliff - Enables changelog generation with templates and commit parsing - Configures commit grouping, tag patterns, and remote repository details	2025-05-08 19:01:55 +02:00
Max P.	7b6eb2b574	feat(workflows): add upload assets template for releases - Introduces a workflow to automate uploading release assets - Triggers on published releases and uses custom scripts - Enhances release management by linking artifacts to releases	2025-05-08 19:01:37 +02:00
Max P.	f0838567b4	chore(gitignore): add .gitea/COMMIT_GPT.md to ignored files - Adds .gitea/COMMIT_GPT.md to the .gitignore file to exclude it from version control.	2025-05-08 19:01:27 +02:00
Max P.	b009b5763d	feat(config): add project metadata and test watch task - Introduce name and description fields for project metadata - Add a test:watch task for running tests in watch mode - Improve configuration clarity by adjusting formatting	2025-05-08 19:01:03 +02:00