From 2427c07f4c102e149b7464106c1766826901a0e0 Mon Sep 17 00:00:00 2001
From: ArthurErlich <a.erlich@live.de>
Date: Sat, 30 May 2026 12:38:23 +0200
Subject: [PATCH 01/15] feat(docker): add FrankenPHP Caddy configuration

Add production and dev Caddyfiles for FrankenPHP:
- Caddyfile: HTTP-only on :8080, auto_https off, worker mode
- Caddyfile.dev: same but without worker directive so Xdebug
  step-debugging remains functional; Caddy debug logging enabled

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 docker/frankenphp/Caddyfile     | 13 +++++++++++++
 docker/frankenphp/Caddyfile.dev | 12 ++++++++++++
 2 files changed, 25 insertions(+)
 create mode 100644 docker/frankenphp/Caddyfile
 create mode 100644 docker/frankenphp/Caddyfile.dev

diff --git a/docker/frankenphp/Caddyfile b/docker/frankenphp/Caddyfile
new file mode 100644
index 0000000..2234c7b
--- /dev/null
+++ b/docker/frankenphp/Caddyfile
@@ -0,0 +1,13 @@
+{
+    admin off
+    auto_https off
+
+    frankenphp {
+        worker /app/public/worker.php
+    }
+}
+
+:8080 {
+    root * /app/public
+    php_server
+}
diff --git a/docker/frankenphp/Caddyfile.dev b/docker/frankenphp/Caddyfile.dev
new file mode 100644
index 0000000..37f2f0f
--- /dev/null
+++ b/docker/frankenphp/Caddyfile.dev
@@ -0,0 +1,12 @@
+{
+    admin off
+    auto_https off
+    debug
+
+    frankenphp
+}
+
+:8080 {
+    root * /app/public
+    php_server
+}

From 4654a287a8c1cd34869dcc9d597fcea38ade531d Mon Sep 17 00:00:00 2001
From: ArthurErlich <a.erlich@live.de>
Date: Sat, 30 May 2026 12:38:27 +0200
Subject: [PATCH 02/15] feat(app): add FrankenPHP worker script for Symfony

Boot the Symfony kernel once at startup, then loop with
frankenphp_handle_request() to handle every incoming request without
re-bootstrapping the framework. Supports MAX_REQUESTS env var for
graceful worker restarts.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 public/worker.php | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)
 create mode 100644 public/worker.php

diff --git a/public/worker.php b/public/worker.php
new file mode 100644
index 0000000..4b392a3
--- /dev/null
+++ b/public/worker.php
@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+
+use App\Kernel;
+use Symfony\Component\HttpFoundation\Request;
+
+require_once dirname(__DIR__).'/vendor/autoload.php';
+
+$kernel = new Kernel($_SERVER['APP_ENV'] ?? 'prod', (bool) ($_SERVER['APP_DEBUG'] ?? false));
+$kernel->boot();
+
+$handler = static function () use ($kernel): void {
+    $request = Request::createFromGlobals();
+    $response = $kernel->handle($request);
+    $response->send();
+    $kernel->terminate($request, $response);
+};
+
+$maxRequests = (int) ($_SERVER['MAX_REQUESTS'] ?? 0);
+$requestCount = 0;
+
+while (\frankenphp_handle_request($handler)) {
+    if ($maxRequests > 0 && ++$requestCount >= $maxRequests) {
+        break;
+    }
+}
+
+$kernel->shutdown();

From 92380e534af344a69f9cc4540358dd6ce485c799 Mon Sep 17 00:00:00 2001
From: ArthurErlich <a.erlich@live.de>
Date: Sat, 30 May 2026 12:38:38 +0200
Subject: [PATCH 03/15] feat(docker): migrate base image from php-cli to
 FrankenPHP Alpine
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Replace php:8.4-cli-alpine3.21 with dunglas/frankenphp:1-php8.4-alpine.
No Go toolchain required — the official image ships as a pre-compiled
Alpine binary.

- Drop docker-php-ext-install opcache (FrankenPHP enables it by default)
- Both dev and final stages run frankenphp run --config /etc/caddy/Caddyfile
- Dev stage bakes in Caddyfile.dev (no worker mode, Xdebug compatible)
- Final stage bakes in production Caddyfile

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 Dockerfile | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/Dockerfile b/Dockerfile
index 20eaae1..267b8e0 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -1,10 +1,9 @@
-FROM php:8.4-cli-alpine3.21 AS base
+FROM dunglas/frankenphp:1-php8.4-alpine AS base
 
 RUN apk add --no-cache \
     curl \
     icu-libs \
-    libzip \
-    && docker-php-ext-install opcache
+    libzip
 
 WORKDIR /app
 
@@ -32,11 +31,12 @@ RUN apk add --no-cache ${PHPIZE_DEPS} linux-headers \
     && docker-php-ext-enable xdebug \
     && apk del ${PHPIZE_DEPS}
 COPY docker/php/xdebug.ini /usr/local/etc/php/conf.d/docker-xdebug.ini
+COPY docker/frankenphp/Caddyfile.dev /etc/caddy/Caddyfile
 COPY composer.json composer.lock* ./
 RUN composer install --no-scripts --no-interaction --prefer-dist
 EXPOSE 8080
 ENV APP_ENV=dev APP_DEBUG=1
-CMD ["php", "-S", "0.0.0.0:8080", "-t", "public", "public/index.php"]
+CMD ["frankenphp", "run", "--config", "/etc/caddy/Caddyfile"]
 
 # ── final (prod) stage — no composer binary ────────────────────────────────────
 FROM base AS final
@@ -45,6 +45,7 @@ RUN addgroup -S app && adduser -S -G app app
 
 COPY --from=build /app/vendor /app/vendor
 COPY . .
+COPY docker/frankenphp/Caddyfile /etc/caddy/Caddyfile
 
 RUN mkdir -p var/cache var/log \
     && chown -R app:app /app
@@ -54,4 +55,4 @@ USER app
 EXPOSE 8080
 ENV APP_ENV=prod APP_DEBUG=0
 
-CMD ["php", "-S", "0.0.0.0:8080", "-t", "public", "public/index.php"]
+CMD ["frankenphp", "run", "--config", "/etc/caddy/Caddyfile"]

From 235e63bfc0ab470e15c9d1a24fe68fd2a8c94a35 Mon Sep 17 00:00:00 2001
From: ArthurErlich <a.erlich@live.de>
Date: Sat, 30 May 2026 12:39:29 +0200
Subject: [PATCH 04/15] fix(config): add default empty values for optional env
 vars

Declare empty-string defaults for all optional env vars as Symfony
parameters so the container compiles without errors when GITHUB_USER,
GITLAB_TOKEN, GITEA_URL, etc. are not set in the environment.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 config/services.yaml | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/config/services.yaml b/config/services.yaml
index 7888e8b..138555e 100644
--- a/config/services.yaml
+++ b/config/services.yaml
@@ -1,3 +1,15 @@
+parameters:
+    env(APP_SECRET): ''
+    env(ALLOWED_HOSTS): ''
+    env(GITHUB_USER): ''
+    env(GITHUB_TOKEN): ''
+    env(GITLAB_USER): ''
+    env(GITLAB_TOKEN): ''
+    env(GITLAB_URL): ''
+    env(GITEA_USER): ''
+    env(GITEA_TOKEN): ''
+    env(GITEA_URL): ''
+
 services:
     _defaults:
         autowire: true

From 5b07eae67257e5bd2338954782ef53d3b56ecb86 Mon Sep 17 00:00:00 2001
From: ArthurErlich <a.erlich@live.de>
Date: Sat, 30 May 2026 12:39:33 +0200
Subject: [PATCH 05/15] docs: update installation guide to use pre-built image

Replace the clone-and-build workflow with a docker-compose snippet
that pulls the image directly from the Gitea container registry.
Add semver tag reference and rename steps to match the new flow.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 README.md | 42 ++++++++++++++++++++++++++++++++----------
 1 file changed, 32 insertions(+), 10 deletions(-)

diff --git a/README.md b/README.md
index 234c1d1..a6022bd 100644
--- a/README.md
+++ b/README.md
@@ -27,15 +27,36 @@ https://your-host/graph.svg?theme=dark
 
 - Docker + Docker Compose
 
-### 1. Clone and configure
+### 1. Create a `docker-compose.yml`
 
-```bash
-git clone https://git.arthurerlich.de/haylan/git-contribution-graph.git
-cd git-contribution-graph
-cp .env .env.local
+Use the pre-built image — no need to clone the repo:
+
+```yaml
+services:
+  graph:
+    image: git.arthurerlich.de/haylan/git-contribution-graph:latest
+    ports:
+      - "8080:8080"
+    env_file:
+      - .env.local
+    volumes:
+      - cache:/var/www/html/var/cache
+
+volumes:
+  cache:
 ```
 
-Edit `.env.local` with your credentials:
+The image is published to the Gitea container registry. Pull it manually with:
+
+```bash
+docker pull git.arthurerlich.de/haylan/git-contribution-graph:latest
+```
+
+Semver tags are published (`0`, `0.0`, `0.0.1`) alongside `latest` — see the [container registry](https://git.arthurerlich.de/haylan/-/packages/container/git-contribution-graph/latest) for all available tags.
+
+### 2. Configure
+
+Create a `.env.local` file next to your `docker-compose.yml`:
 
 ```dotenv
 APP_SECRET=<generate with: openssl rand -hex 16>
@@ -60,7 +81,7 @@ ALLOWED_HOSTS=
 
 Only configure the platforms you use — unused ones are silently skipped.
 
-### 2. Start
+### 3. Start
 
 ```bash
 docker compose up -d
@@ -68,10 +89,11 @@ docker compose up -d
 
 The service listens on **port 8080** by default. Put Traefik or nginx in front of it for HTTPS.
 
-### 3. Health check
+### 4. Verify
 
-```
-GET /health  →  {"status":"ok"}
+```bash
+curl http://localhost:8080/health
+# {"status":"ok"}
 ```
 
 ---

From 3e3a6752afdf1162513bde7e94d61cfa5423234b Mon Sep 17 00:00:00 2001
From: ArthurErlich <a.erlich@live.de>
Date: Sat, 30 May 2026 12:39:39 +0200
Subject: [PATCH 06/15] chore(dev): remove broken auto-run PHPUnit hook

The PostToolUse hook called php bin/phpunit directly, which does not
work inside the Docker-based dev setup. Remove it; tests should be
run via docker compose exec graph vendor/bin/phpunit as documented.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .claude/settings.json | 11 +----------
 1 file changed, 1 insertion(+), 10 deletions(-)

diff --git a/.claude/settings.json b/.claude/settings.json
index bc91e4b..9e26dfe 100644
--- a/.claude/settings.json
+++ b/.claude/settings.json
@@ -1,10 +1 @@
-{
-    "hooks": {
-        "PostToolUse": [
-            {
-                "matcher": "Edit|Write",
-                "command": "php bin/phpunit 2>&1 | tail -20"
-            }
-        ]
-    }
-}
+{}
\ No newline at end of file

From c205fed14b8b98839d06e2f4a0bfd593d80964e3 Mon Sep 17 00:00:00 2001
From: ArthurErlich <a.erlich@live.de>
Date: Sat, 30 May 2026 12:58:17 +0200
Subject: [PATCH 07/15] refactor(controller): extract contribution aggregation
 into dedicated service

Move fetchAllContributions and merge logic from GraphController into a new
ContributionAggregator service. Replace deprecated TaggedIterator with
AutowireIterator throughout.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/Controller/GraphController.php     | 37 ++----------------------
 src/Service/ContributionAggregator.php | 40 ++++++++++++++++++++++++++
 2 files changed, 43 insertions(+), 34 deletions(-)
 create mode 100644 src/Service/ContributionAggregator.php

diff --git a/src/Controller/GraphController.php b/src/Controller/GraphController.php
index 455b980..6fbec66 100644
--- a/src/Controller/GraphController.php
+++ b/src/Controller/GraphController.php
@@ -2,11 +2,10 @@
 
 namespace App\Controller;
 
-use App\Service\ProviderInterface;
+use App\Service\ContributionAggregator;
 use App\Service\SvgRenderer;
 use Psr\Log\LoggerInterface;
 use Symfony\Component\DependencyInjection\Attribute\Autowire;
-use Symfony\Component\DependencyInjection\Attribute\TaggedIterator;
 use Symfony\Component\HttpFoundation\RedirectResponse;
 use Symfony\Component\HttpFoundation\Request;
 use Symfony\Component\HttpFoundation\Response;
@@ -20,8 +19,7 @@ class GraphController
     private readonly array $allowedHosts;
 
     public function __construct(
-        #[TaggedIterator('app.provider')]
-        private readonly iterable $providers,
+        private readonly ContributionAggregator $aggregator,
         private readonly SvgRenderer $renderer,
         private readonly CacheInterface $cache,
         private readonly LoggerInterface $logger,
@@ -52,7 +50,7 @@ class GraphController
             $cacheMiss = true;
             $item->expiresAfter(3600);
 
-            return $this->renderer->render($this->fetchAllContributions(), $theme);
+            return $this->renderer->render($this->aggregator->aggregate(), $theme);
         });
 
         $this->logger->debug('GraphController: cache ' . ($cacheMiss ? 'miss' : 'hit'), ['theme' => $theme]);
@@ -78,34 +76,5 @@ class GraphController
         return new Response('{"status":"ok"}', 200, ['Content-Type' => 'application/json']);
     }
 
-    /** @return array<string, int> */
-    private function fetchAllContributions(): array
-    {
-        $contributions = [];
 
-        /** @var ProviderInterface $provider */
-        foreach ($this->providers as $provider) {
-            if (!$provider->isConfigured()) {
-                continue;
-            }
-
-            try {
-                $contributions = $this->merge($contributions, $provider->fetch());
-            } catch (\Throwable $e) {
-                $this->logger->warning(sprintf('%s fetch failed: %s', $provider::class, $e->getMessage()), ['exception' => $e]);
-            }
-        }
-
-        return $contributions;
-    }
-
-    /** @param array<string, int> $base @param array<string, int> $new @return array<string, int> */
-    private function merge(array $base, array $new): array
-    {
-        foreach ($new as $date => $count) {
-            $base[$date] = ($base[$date] ?? 0) + $count;
-        }
-
-        return $base;
-    }
 }
diff --git a/src/Service/ContributionAggregator.php b/src/Service/ContributionAggregator.php
new file mode 100644
index 0000000..370d05f
--- /dev/null
+++ b/src/Service/ContributionAggregator.php
@@ -0,0 +1,40 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Service;
+
+use Psr\Log\LoggerInterface;
+use Symfony\Component\DependencyInjection\Attribute\AutowireIterator;
+
+final class ContributionAggregator
+{
+    public function __construct(
+        #[AutowireIterator('app.provider')]
+        private readonly iterable $providers,
+        private readonly LoggerInterface $logger,
+    ) {}
+
+    /** @return array<string, int> */
+    public function aggregate(): array
+    {
+        $contributions = [];
+
+        /** @var ProviderInterface $provider */
+        foreach ($this->providers as $provider) {
+            if (!$provider->isConfigured()) {
+                continue;
+            }
+
+            try {
+                foreach ($provider->fetch() as $date => $count) {
+                    $contributions[$date] = ($contributions[$date] ?? 0) + $count;
+                }
+            } catch (\Throwable $e) {
+                $this->logger->warning(sprintf('%s fetch failed: %s', $provider::class, $e->getMessage()), ['exception' => $e]);
+            }
+        }
+
+        return $contributions;
+    }
+}

From 225c6140576ebee1823a8f65e3972ba24baf956a Mon Sep 17 00:00:00 2001
From: ArthurErlich <a.erlich@live.de>
Date: Sat, 30 May 2026 12:58:23 +0200
Subject: [PATCH 08/15] test(service): refactor SvgRendererTest to follow
 PHPUnit best practices

- Replace setUp() factory with direct instantiation (zero-param constructor)
- Add AAA blank-line separators to all test methods
- Consolidate theme + fallback tests behind a DataProvider
- Consolidate day-of-week label tests behind a DataProvider
- Split multi-assertion tests to one assertion per test

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 tests/Unit/Service/SvgRendererTest.php | 85 +++++++++++++++-----------
 1 file changed, 49 insertions(+), 36 deletions(-)

diff --git a/tests/Unit/Service/SvgRendererTest.php b/tests/Unit/Service/SvgRendererTest.php
index 346f0cb..1576650 100644
--- a/tests/Unit/Service/SvgRendererTest.php
+++ b/tests/Unit/Service/SvgRendererTest.php
@@ -6,65 +6,65 @@ namespace App\Tests\Unit\Service;
 
 use App\Service\SvgRenderer;
 use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\DataProvider;
 use PHPUnit\Framework\Attributes\Test;
 use PHPUnit\Framework\TestCase;
 
 #[CoversClass(SvgRenderer::class)]
 final class SvgRendererTest extends TestCase
 {
-    private SvgRenderer $renderer;
-
-    protected function setUp(): void
+    #[Test]
+    public function it_returns_an_svg_opening_tag(): void
     {
-        $this->renderer = new SvgRenderer();
+        $svg = (new SvgRenderer())->render([]);
+
+        $this->assertStringStartsWith('<svg', $svg);
     }
 
     #[Test]
-    public function it_returns_a_valid_svg_element(): void
+    public function it_returns_a_closed_svg_element(): void
     {
-        $svg = $this->renderer->render([]);
+        $svg = (new SvgRenderer())->render([]);
 
-        $this->assertStringStartsWith('<svg', $svg);
         $this->assertStringEndsWith('</svg>', $svg);
     }
 
     #[Test]
-    public function it_includes_accessibility_attributes(): void
+    public function it_includes_role_img_attribute_for_accessibility(): void
     {
-        $svg = $this->renderer->render([]);
+        $svg = (new SvgRenderer())->render([]);
 
         $this->assertStringContainsString('role="img"', $svg);
+    }
+
+    #[Test]
+    public function it_includes_aria_label_attribute_for_accessibility(): void
+    {
+        $svg = (new SvgRenderer())->render([]);
+
         $this->assertStringContainsString('aria-label="Contribution graph"', $svg);
     }
 
     #[Test]
-    public function it_applies_dark_theme_background_color(): void
+    #[DataProvider('theme_background_provider')]
+    public function it_applies_background_color_for_theme(string $theme, string $expectedColor): void
     {
-        $svg = $this->renderer->render([], 'dark');
+        $svg = (new SvgRenderer())->render([], $theme);
 
-        $this->assertStringContainsString('#0d1117', $svg);
+        $this->assertStringContainsString($expectedColor, $svg);
     }
 
-    #[Test]
-    public function it_applies_light_theme_background_color(): void
+    public static function theme_background_provider(): iterable
     {
-        $svg = $this->renderer->render([], 'light');
-
-        $this->assertStringContainsString('#ffffff', $svg);
-    }
-
-    #[Test]
-    public function it_falls_back_to_dark_theme_for_unknown_theme_names(): void
-    {
-        $svg = $this->renderer->render([], 'unknown');
-
-        $this->assertStringContainsString('#0d1117', $svg);
+        yield 'dark theme'    => ['dark',    '#0d1117'];
+        yield 'light theme'   => ['light',   '#ffffff'];
+        yield 'unknown theme' => ['unknown', '#0d1117'];
     }
 
     #[Test]
     public function it_shows_zero_contributions_when_no_data_is_provided(): void
     {
-        $svg = $this->renderer->render([]);
+        $svg = (new SvgRenderer())->render([]);
 
         $this->assertStringContainsString('0 contributions in the last year', $svg);
     }
@@ -74,7 +74,7 @@ final class SvgRendererTest extends TestCase
     {
         $today = (new \DateTimeImmutable('today'))->format('Y-m-d');
 
-        $svg = $this->renderer->render([$today => 1234]);
+        $svg = (new SvgRenderer())->render([$today => 1234]);
 
         $this->assertStringContainsString('1,234 contributions in the last year', $svg);
     }
@@ -82,28 +82,41 @@ final class SvgRendererTest extends TestCase
     #[Test]
     public function it_renders_all_53_week_columns(): void
     {
-        $svg = $this->renderer->render([]);
+        $svg = (new SvgRenderer())->render([]);
 
         // MARGIN_X(28) + col_52 * STEP(13) = 704
         $this->assertStringContainsString('x="704"', $svg);
     }
 
     #[Test]
-    public function it_renders_day_of_week_labels_matching_github(): void
+    #[DataProvider('day_of_week_label_provider')]
+    public function it_renders_day_of_week_label(string $label): void
     {
-        $svg = $this->renderer->render([]);
+        $svg = (new SvgRenderer())->render([]);
 
-        $this->assertStringContainsString('>Mon<', $svg);
-        $this->assertStringContainsString('>Wed<', $svg);
-        $this->assertStringContainsString('>Fri<', $svg);
+        $this->assertStringContainsString('>' . $label . '<', $svg);
+    }
+
+    public static function day_of_week_label_provider(): iterable
+    {
+        yield 'Monday'    => ['Mon'];
+        yield 'Wednesday' => ['Wed'];
+        yield 'Friday'    => ['Fri'];
     }
 
     #[Test]
-    public function it_renders_a_legend_with_less_and_more_labels(): void
+    public function it_renders_a_less_label_in_the_legend(): void
     {
-        $svg = $this->renderer->render([]);
+        $svg = (new SvgRenderer())->render([]);
 
         $this->assertStringContainsString('>Less<', $svg);
+    }
+
+    #[Test]
+    public function it_renders_a_more_label_in_the_legend(): void
+    {
+        $svg = (new SvgRenderer())->render([]);
+
         $this->assertStringContainsString('>More<', $svg);
     }
 
@@ -113,7 +126,7 @@ final class SvgRendererTest extends TestCase
         $today     = (new \DateTimeImmutable('today'))->format('Y-m-d');
         $yesterday = (new \DateTimeImmutable('yesterday'))->format('Y-m-d');
 
-        $svg = $this->renderer->render([$today => 3, $yesterday => 7]);
+        $svg = (new SvgRenderer())->render([$today => 3, $yesterday => 7]);
 
         $this->assertStringContainsString('10 contributions in the last year', $svg);
     }

From 71bfb38028ed519119ab58aab7397c205f1b0446 Mon Sep 17 00:00:00 2001
From: ArthurErlich <a.erlich@live.de>
Date: Sat, 30 May 2026 14:13:07 +0200
Subject: [PATCH 09/15] feat(provider): add health-probe contract and
 supporting value objects

Add getName(), ping(), and probe() to ProviderInterface. Introduce
ProbeTrait to classify HTTP/transport exceptions into typed error codes,
ProviderStatus as the result value object, and ProviderStatusType /
ProviderErrorCode as backing enums.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/Service/ProbeTrait.php         | 63 ++++++++++++++++++++++++++++++
 src/Service/ProviderErrorCode.php  | 13 ++++++
 src/Service/ProviderInterface.php  |  6 +++
 src/Service/ProviderStatus.php     | 29 ++++++++++++++
 src/Service/ProviderStatusType.php | 12 ++++++
 5 files changed, 123 insertions(+)
 create mode 100644 src/Service/ProbeTrait.php
 create mode 100644 src/Service/ProviderErrorCode.php
 create mode 100644 src/Service/ProviderStatus.php
 create mode 100644 src/Service/ProviderStatusType.php

diff --git a/src/Service/ProbeTrait.php b/src/Service/ProbeTrait.php
new file mode 100644
index 0000000..af86c33
--- /dev/null
+++ b/src/Service/ProbeTrait.php
@@ -0,0 +1,63 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Service;
+
+use Symfony\Contracts\HttpClient\Exception\HttpExceptionInterface;
+use Symfony\Contracts\HttpClient\Exception\TransportExceptionInterface;
+
+trait ProbeTrait
+{
+    public function probe(): ProviderStatus
+    {
+        if (!$this->isConfigured()) {
+            return new ProviderStatus($this->getName(), ProviderStatusType::NotConfigured);
+        }
+
+        try {
+            $this->ping();
+
+            return new ProviderStatus($this->getName(), ProviderStatusType::Ok);
+        } catch (\Throwable $e) {
+            return $this->statusFromException($e);
+        }
+    }
+
+    private function statusFromException(\Throwable $e): ProviderStatus
+    {
+        [$error, $message] = $this->classifyException($e);
+
+        return new ProviderStatus($this->getName(), ProviderStatusType::Error, $error, $message);
+    }
+
+    /** @return array{ProviderErrorCode, string} */
+    private function classifyException(\Throwable $e): array
+    {
+        if ($e instanceof TransportExceptionInterface) {
+            return [ProviderErrorCode::UrlUnreachable, 'Could not reach the server: ' . $e->getMessage()];
+        }
+
+        if ($e instanceof HttpExceptionInterface) {
+            $code = $e->getResponse()->getStatusCode();
+
+            return match (true) {
+                $code === 401 => [ProviderErrorCode::AuthFailed, 'Invalid or expired token — verify your credentials'],
+                $code === 403 => [ProviderErrorCode::AuthFailed, 'Access denied — token lacks the required scopes'],
+                $code === 404 => [ProviderErrorCode::UrlUnreachable, 'Endpoint not found — check the configured URL'],
+                default       => [ProviderErrorCode::Unknown, "HTTP {$code}: " . $e->getMessage()],
+            };
+        }
+
+        $msg   = $e->getMessage();
+        $lower = strtolower($msg);
+        $error = match (true) {
+            str_contains($msg, 'not found') || str_contains($msg, 'Could not resolve') => ProviderErrorCode::UserNotFound,
+            str_contains($msg, 'GraphQL error')
+                && (str_contains($lower, 'unauthorized') || str_contains($lower, 'bad credentials')) => ProviderErrorCode::AuthFailed,
+            default => ProviderErrorCode::Unknown,
+        };
+
+        return [$error, $msg];
+    }
+}
diff --git a/src/Service/ProviderErrorCode.php b/src/Service/ProviderErrorCode.php
new file mode 100644
index 0000000..d9c484c
--- /dev/null
+++ b/src/Service/ProviderErrorCode.php
@@ -0,0 +1,13 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Service;
+
+enum ProviderErrorCode: string
+{
+    case AuthFailed     = 'auth_failed';
+    case UrlUnreachable = 'url_unreachable';
+    case UserNotFound   = 'user_not_found';
+    case Unknown        = 'unknown';
+}
diff --git a/src/Service/ProviderInterface.php b/src/Service/ProviderInterface.php
index d58119b..c2ac9ad 100644
--- a/src/Service/ProviderInterface.php
+++ b/src/Service/ProviderInterface.php
@@ -10,4 +10,10 @@ interface ProviderInterface
     public function fetch(): array;
 
     public function isConfigured(): bool;
+
+    public function getName(): string;
+
+    public function probe(): ProviderStatus;
+
+    public function ping(): void;
 }
diff --git a/src/Service/ProviderStatus.php b/src/Service/ProviderStatus.php
new file mode 100644
index 0000000..0483afa
--- /dev/null
+++ b/src/Service/ProviderStatus.php
@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Service;
+
+final class ProviderStatus
+{
+    public function __construct(
+        public readonly string $name,
+        public readonly ProviderStatusType $status,
+        public readonly ?ProviderErrorCode $error = null,
+        public readonly ?string $message = null,
+    ) {}
+
+    /** @return array<string, string> */
+    public function toArray(): array
+    {
+        $data = ['status' => $this->status->value];
+        if ($this->error !== null) {
+            $data['error'] = $this->error->value;
+        }
+        if ($this->message !== null) {
+            $data['message'] = $this->message;
+        }
+
+        return $data;
+    }
+}
diff --git a/src/Service/ProviderStatusType.php b/src/Service/ProviderStatusType.php
new file mode 100644
index 0000000..29031e1
--- /dev/null
+++ b/src/Service/ProviderStatusType.php
@@ -0,0 +1,12 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Service;
+
+enum ProviderStatusType: string
+{
+    case Ok            = 'ok';
+    case Error         = 'error';
+    case NotConfigured = 'not_configured';
+}

From d3b9463c57a423c3eb8bd5a3ceed406f90bf07a5 Mon Sep 17 00:00:00 2001
From: ArthurErlich <a.erlich@live.de>
Date: Sat, 30 May 2026 14:13:14 +0200
Subject: [PATCH 10/15] feat(provider): implement ping and probe on GitHub,
 GitLab, and Gitea

Add getName() and ping() to each provider and wire ProbeTrait. Make
all classes final, add strict_types declarations, and replace generic
RuntimeException with typed HTTP exceptions so probe() can classify
auth failures and unreachable endpoints correctly.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/Service/GitHubProvider.php | 21 +++++++++++++++++++--
 src/Service/GitLabProvider.php | 24 +++++++++++++++++++++---
 src/Service/GiteaProvider.php  | 22 ++++++++++++++++++++--
 3 files changed, 60 insertions(+), 7 deletions(-)

diff --git a/src/Service/GitHubProvider.php b/src/Service/GitHubProvider.php
index ea90ea3..49bf749 100644
--- a/src/Service/GitHubProvider.php
+++ b/src/Service/GitHubProvider.php
@@ -1,10 +1,13 @@
 <?php
 
+declare(strict_types=1);
+
 namespace App\Service;
 
 use IDCI\Bundle\GraphQLClientBundle\Client\GraphQLApiClient;
 use IDCI\Bundle\GraphQLClientBundle\Client\GraphQLApiClientRegistryInterface;
 use Psr\Log\LoggerInterface;
+use Symfony\Component\HttpKernel\Exception\ServiceUnavailableHttpException;
 use Symfony\Contracts\HttpClient\HttpClientInterface;
 
 /**
@@ -12,8 +15,10 @@ use Symfony\Contracts\HttpClient\HttpClientInterface;
  *
  * Required token scopes: read:user
  */
-class GitHubProvider implements ProviderInterface
+final class GitHubProvider implements ProviderInterface
 {
+    use ProbeTrait;
+
     private const GRAPHQL_URL = 'https://api.github.com/graphql';
 
     public function __construct(
@@ -24,11 +29,23 @@ class GitHubProvider implements ProviderInterface
         private readonly LoggerInterface $logger,
     ) {}
 
+    public function getName(): string
+    {
+        return 'github';
+    }
+
     public function isConfigured(): bool
     {
         return $this->username !== '' && $this->token !== '';
     }
 
+    public function ping(): void
+    {
+        $this->client->request('GET', 'https://api.github.com/user', [
+            'headers' => ['Authorization' => "Bearer {$this->token}"],
+        ])->getContent();
+    }
+
     /**
      * @return array<string, int>  date (Y-m-d) => contribution count
      */
@@ -69,7 +86,7 @@ class GitHubProvider implements ProviderInterface
         $data = $response->toArray();
 
         if (isset($data['errors'])) {
-            throw new \RuntimeException('GitHub GraphQL error: ' . json_encode($data['errors']));
+            throw new ServiceUnavailableHttpException(null, 'GitHub GraphQL error: ' . json_encode($data['errors']));
         }
 
         $result = [];
diff --git a/src/Service/GitLabProvider.php b/src/Service/GitLabProvider.php
index 802f046..d903730 100644
--- a/src/Service/GitLabProvider.php
+++ b/src/Service/GitLabProvider.php
@@ -1,8 +1,11 @@
 <?php
 
+declare(strict_types=1);
+
 namespace App\Service;
 
 use Psr\Log\LoggerInterface;
+use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;
 use Symfony\Contracts\HttpClient\HttpClientInterface;
 
 /**
@@ -11,8 +14,10 @@ use Symfony\Contracts\HttpClient\HttpClientInterface;
  * Required token scopes: read_user, read_api
  * Works with both gitlab.com and self-hosted instances.
  */
-class GitLabProvider implements ProviderInterface
+final class GitLabProvider implements ProviderInterface
 {
+    use ProbeTrait;
+
     public function __construct(
         private readonly HttpClientInterface $client,
         private readonly string $username,
@@ -21,11 +26,25 @@ class GitLabProvider implements ProviderInterface
         private readonly string $baseUrl = '',
     ) {}
 
+    public function getName(): string
+    {
+        return 'gitlab';
+    }
+
     public function isConfigured(): bool
     {
         return $this->username !== '' && $this->token !== '';
     }
 
+    public function ping(): void
+    {
+        $baseUrl = rtrim($this->baseUrl !== '' ? $this->baseUrl : 'https://gitlab.com', '/');
+
+        $this->client->request('GET', "$baseUrl/api/v4/user", [
+            'headers' => ['PRIVATE-TOKEN' => $this->token],
+        ])->getContent();
+    }
+
     /**
      * @return array<string, int>  date (Y-m-d) => event count
      */
@@ -35,7 +54,6 @@ class GitLabProvider implements ProviderInterface
 
         $this->logger->debug('GitLabProvider: fetching contributions', ['user' => $this->username, 'url' => $baseUrl]);
 
-        // Resolve numeric user ID from username
         $userResponse = $this->client->request('GET', "$baseUrl/api/v4/users", [
             'headers' => ['PRIVATE-TOKEN' => $this->token],
             'query'   => ['username' => $this->username],
@@ -43,7 +61,7 @@ class GitLabProvider implements ProviderInterface
 
         $users = $userResponse->toArray();
         if (empty($users)) {
-            throw new \RuntimeException("GitLab: user '{$this->username}' not found on $baseUrl");
+            throw new NotFoundHttpException("GitLab: user '{$this->username}' not found on $baseUrl");
         }
         $userId = $users[0]['id'];
 
diff --git a/src/Service/GiteaProvider.php b/src/Service/GiteaProvider.php
index c9f3c88..e3b75b1 100644
--- a/src/Service/GiteaProvider.php
+++ b/src/Service/GiteaProvider.php
@@ -1,5 +1,7 @@
 <?php
 
+declare(strict_types=1);
+
 namespace App\Service;
 
 use Psr\Log\LoggerInterface;
@@ -13,8 +15,10 @@ use Symfony\Contracts\HttpClient\HttpClientInterface;
  *
  * Required token scopes: read:user
  */
-class GiteaProvider implements ProviderInterface
+final class GiteaProvider implements ProviderInterface
 {
+    use ProbeTrait;
+
     public function __construct(
         private readonly HttpClientInterface $client,
         private readonly string $username,
@@ -23,17 +27,31 @@ class GiteaProvider implements ProviderInterface
         private readonly LoggerInterface $logger,
     ) {}
 
+    public function getName(): string
+    {
+        return 'gitea';
+    }
+
     public function isConfigured(): bool
     {
         return $this->username !== '' && $this->token !== '' && $this->baseUrl !== '';
     }
 
+    public function ping(): void
+    {
+        $baseUrl = rtrim($this->baseUrl, '/');
+
+        $this->client->request('GET', "$baseUrl/api/v1/user", [
+            'headers' => ['Authorization' => "token {$this->token}"],
+        ])->getContent();
+    }
+
     /**
      * @return array<string, int>  date (Y-m-d) => contribution count
      */
     public function fetch(): array
     {
-        $baseUrl  = rtrim($this->baseUrl, '/');
+        $baseUrl = rtrim($this->baseUrl, '/');
 
         $this->logger->debug('GiteaProvider: fetching contributions', ['user' => $this->username, 'url' => $baseUrl]);
 

From c70d96c3aaf53c8be26a5e3e56dbae99b27cc0ec Mon Sep 17 00:00:00 2001
From: ArthurErlich <a.erlich@live.de>
Date: Sat, 30 May 2026 14:13:24 +0200
Subject: [PATCH 11/15] feat(health): make /health report per-provider probe
 status

Introduce ProviderHealthChecker which probes each configured provider
via AutowireIterator. Wire it into GraphController so /health returns
detailed per-provider status and responds 503 when any provider is
in a degraded state.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/Controller/GraphController.php    | 17 +++++++++---
 src/Service/ProviderHealthChecker.php | 39 +++++++++++++++++++++++++++
 2 files changed, 52 insertions(+), 4 deletions(-)
 create mode 100644 src/Service/ProviderHealthChecker.php

diff --git a/src/Controller/GraphController.php b/src/Controller/GraphController.php
index 6fbec66..d9f15f6 100644
--- a/src/Controller/GraphController.php
+++ b/src/Controller/GraphController.php
@@ -1,8 +1,11 @@
 <?php
 
+declare(strict_types=1);
+
 namespace App\Controller;
 
 use App\Service\ContributionAggregator;
+use App\Service\ProviderHealthChecker;
 use App\Service\SvgRenderer;
 use Psr\Log\LoggerInterface;
 use Symfony\Component\DependencyInjection\Attribute\Autowire;
@@ -13,7 +16,7 @@ use Symfony\Component\Routing\Attribute\Route;
 use Symfony\Contracts\Cache\CacheInterface;
 use Symfony\Contracts\Cache\ItemInterface;
 
-class GraphController
+final class GraphController
 {
     /** @var list<string> */
     private readonly array $allowedHosts;
@@ -23,6 +26,7 @@ class GraphController
         private readonly SvgRenderer $renderer,
         private readonly CacheInterface $cache,
         private readonly LoggerInterface $logger,
+        private readonly ProviderHealthChecker $healthChecker,
         #[Autowire(env: 'ALLOWED_HOSTS')]
         string $allowedHosts = '',
     ) {
@@ -73,8 +77,13 @@ class GraphController
     #[Route('/health', name: 'health', methods: ['GET'])]
     public function health(): Response
     {
-        return new Response('{"status":"ok"}', 200, ['Content-Type' => 'application/json']);
+        $result     = $this->healthChecker->check();
+        $statusCode = $result['status'] === 'degraded' ? 503 : 200;
+
+        return new Response(
+            json_encode($result, JSON_PRETTY_PRINT | JSON_THROW_ON_ERROR),
+            $statusCode,
+            ['Content-Type' => 'application/json'],
+        );
     }
-
-
 }
diff --git a/src/Service/ProviderHealthChecker.php b/src/Service/ProviderHealthChecker.php
new file mode 100644
index 0000000..8ffe9a0
--- /dev/null
+++ b/src/Service/ProviderHealthChecker.php
@@ -0,0 +1,39 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Service;
+
+use Symfony\Component\DependencyInjection\Attribute\AutowireIterator;
+
+final class ProviderHealthChecker
+{
+    public function __construct(
+        #[AutowireIterator('app.provider')]
+        private readonly iterable $providers,
+    ) {}
+
+    /**
+     * @return array{status: string, providers: array<string, array<string, string>>}
+     */
+    public function check(): array
+    {
+        $statuses = [];
+        $hasError = false;
+
+        /** @var ProviderInterface $provider */
+        foreach ($this->providers as $provider) {
+            $status                  = $provider->probe();
+            $statuses[$status->name] = $status->toArray();
+
+            if ($status->status === ProviderStatusType::Error) {
+                $hasError = true;
+            }
+        }
+
+        return [
+            'status'    => $hasError ? 'degraded' : 'ok',
+            'providers' => $statuses,
+        ];
+    }
+}

From 61b7735afc3ea9279d614f5bee8cb1f3aafa6c2b Mon Sep 17 00:00:00 2001
From: ArthurErlich <a.erlich@live.de>
Date: Sat, 30 May 2026 14:13:51 +0200
Subject: [PATCH 12/15] refactor(renderer): add strict_types declaration and
 make class final

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/Service/SvgRenderer.php | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/src/Service/SvgRenderer.php b/src/Service/SvgRenderer.php
index 2682a81..00ee8d3 100644
--- a/src/Service/SvgRenderer.php
+++ b/src/Service/SvgRenderer.php
@@ -1,5 +1,7 @@
 <?php
 
+declare(strict_types=1);
+
 namespace App\Service;
 
 /**
@@ -11,7 +13,7 @@ namespace App\Service;
  *  - Month labels above, weekday labels (Mon/Wed/Fri) on the left
  *  - 5 intensity levels (0–4) matched to GitHub's colour palette
  */
-class SvgRenderer
+final class SvgRenderer
 {
     // GitHub's exact colour tokens
     private const THEMES = [

From 85428826a0cf7ad77bc6fbb2b8c929a2d25395e4 Mon Sep 17 00:00:00 2001
From: ArthurErlich <a.erlich@live.de>
Date: Sat, 30 May 2026 14:14:06 +0200
Subject: [PATCH 13/15] test(provider): add unit tests for probe infrastructure
 and all providers

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .../Service/ContributionAggregatorTest.php    | 109 +++++++++++++
 tests/Unit/Service/GitHubProviderTest.php     | 146 ++++++++++++++++++
 tests/Unit/Service/GitLabProviderTest.php     | 128 +++++++++++++++
 tests/Unit/Service/GiteaProviderTest.php      | 111 +++++++++++++
 tests/Unit/Service/ProbeTraitTest.php         | 128 +++++++++++++++
 .../Service/ProviderHealthCheckerTest.php     |  88 +++++++++++
 tests/Unit/Service/ProviderStatusTest.php     |  64 ++++++++
 7 files changed, 774 insertions(+)
 create mode 100644 tests/Unit/Service/ContributionAggregatorTest.php
 create mode 100644 tests/Unit/Service/GitHubProviderTest.php
 create mode 100644 tests/Unit/Service/GitLabProviderTest.php
 create mode 100644 tests/Unit/Service/GiteaProviderTest.php
 create mode 100644 tests/Unit/Service/ProbeTraitTest.php
 create mode 100644 tests/Unit/Service/ProviderHealthCheckerTest.php
 create mode 100644 tests/Unit/Service/ProviderStatusTest.php

diff --git a/tests/Unit/Service/ContributionAggregatorTest.php b/tests/Unit/Service/ContributionAggregatorTest.php
new file mode 100644
index 0000000..95f1d8f
--- /dev/null
+++ b/tests/Unit/Service/ContributionAggregatorTest.php
@@ -0,0 +1,109 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Tests\Unit\Service;
+
+use App\Service\ContributionAggregator;
+use App\Service\ProviderInterface;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\TestCase;
+use Psr\Log\LoggerInterface;
+
+#[CoversClass(ContributionAggregator::class)]
+final class ContributionAggregatorTest extends TestCase
+{
+    private LoggerInterface $logger;
+
+    protected function setUp(): void
+    {
+        $this->logger = $this->createStub(LoggerInterface::class);
+    }
+
+    #[Test]
+    public function it_returns_empty_array_when_no_providers_are_given(): void
+    {
+        $aggregator = new ContributionAggregator([], $this->logger);
+
+        $result = $aggregator->aggregate();
+
+        $this->assertSame([], $result);
+    }
+
+    #[Test]
+    public function it_skips_unconfigured_providers(): void
+    {
+        $provider = $this->createStub(ProviderInterface::class);
+        $provider->method('isConfigured')->willReturn(false);
+
+        $aggregator = new ContributionAggregator([$provider], $this->logger);
+
+        $result = $aggregator->aggregate();
+
+        $this->assertSame([], $result);
+    }
+
+    #[Test]
+    public function it_returns_contributions_from_a_configured_provider(): void
+    {
+        $provider = $this->createStub(ProviderInterface::class);
+        $provider->method('isConfigured')->willReturn(true);
+        $provider->method('fetch')->willReturn(['2024-01-01' => 3]);
+
+        $aggregator = new ContributionAggregator([$provider], $this->logger);
+
+        $result = $aggregator->aggregate();
+
+        $this->assertSame(['2024-01-01' => 3], $result);
+    }
+
+    #[Test]
+    public function it_sums_contributions_from_multiple_providers_on_the_same_date(): void
+    {
+        $providerA = $this->createStub(ProviderInterface::class);
+        $providerA->method('isConfigured')->willReturn(true);
+        $providerA->method('fetch')->willReturn(['2024-01-01' => 3, '2024-01-02' => 1]);
+
+        $providerB = $this->createStub(ProviderInterface::class);
+        $providerB->method('isConfigured')->willReturn(true);
+        $providerB->method('fetch')->willReturn(['2024-01-01' => 2, '2024-01-03' => 5]);
+
+        $aggregator = new ContributionAggregator([$providerA, $providerB], $this->logger);
+
+        $result = $aggregator->aggregate();
+
+        $this->assertSame(['2024-01-01' => 5, '2024-01-02' => 1, '2024-01-03' => 5], $result);
+    }
+
+    #[Test]
+    public function it_continues_fetching_remaining_providers_when_one_throws(): void
+    {
+        $failing = $this->createStub(ProviderInterface::class);
+        $failing->method('isConfigured')->willReturn(true);
+        $failing->method('fetch')->willThrowException(new \RuntimeException('Network error'));
+
+        $healthy = $this->createStub(ProviderInterface::class);
+        $healthy->method('isConfigured')->willReturn(true);
+        $healthy->method('fetch')->willReturn(['2024-01-01' => 7]);
+
+        $aggregator = new ContributionAggregator([$failing, $healthy], $this->logger);
+
+        $result = $aggregator->aggregate();
+
+        $this->assertSame(['2024-01-01' => 7], $result);
+    }
+
+    #[Test]
+    public function it_logs_a_warning_when_a_provider_fetch_throws(): void
+    {
+        $logger = $this->createMock(LoggerInterface::class);
+        $logger->expects($this->once())->method('warning');
+
+        $provider = $this->createStub(ProviderInterface::class);
+        $provider->method('isConfigured')->willReturn(true);
+        $provider->method('fetch')->willThrowException(new \RuntimeException('fail'));
+
+        (new ContributionAggregator([$provider], $logger))->aggregate();
+    }
+}
diff --git a/tests/Unit/Service/GitHubProviderTest.php b/tests/Unit/Service/GitHubProviderTest.php
new file mode 100644
index 0000000..daeace5
--- /dev/null
+++ b/tests/Unit/Service/GitHubProviderTest.php
@@ -0,0 +1,146 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Tests\Unit\Service;
+
+use App\Service\GitHubProvider;
+use IDCI\Bundle\GraphQLClientBundle\Client\GraphQLApiClient;
+use IDCI\Bundle\GraphQLClientBundle\Client\GraphQLApiClientRegistryInterface;
+use IDCI\Bundle\GraphQLClientBundle\Query\GraphQLQuery;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\TestCase;
+use Psr\Log\LoggerInterface;
+use Symfony\Component\HttpKernel\Exception\ServiceUnavailableHttpException;
+use Symfony\Contracts\HttpClient\HttpClientInterface;
+use Symfony\Contracts\HttpClient\ResponseInterface;
+
+#[CoversClass(GitHubProvider::class)]
+final class GitHubProviderTest extends TestCase
+{
+    private function makeProvider(
+        string $username = 'user',
+        string $token = 'token',
+        ?HttpClientInterface $client = null,
+        ?GraphQLApiClientRegistryInterface $registry = null,
+    ): GitHubProvider {
+        if ($registry === null) {
+            $graphqlQuery = $this->createStub(GraphQLQuery::class);
+            $graphqlQuery->method('getGraphQLQuery')->willReturn('query {}');
+
+            $graphqlClient = $this->createStub(GraphQLApiClient::class);
+            $graphqlClient->method('buildQuery')->willReturn($graphqlQuery);
+
+            $registry = $this->createStub(GraphQLApiClientRegistryInterface::class);
+            $registry->method('get')->willReturn($graphqlClient);
+        }
+
+        return new GitHubProvider(
+            $client ?? $this->createStub(HttpClientInterface::class),
+            $registry,
+            $username,
+            $token,
+            $this->createStub(LoggerInterface::class),
+        );
+    }
+
+    private function stubGraphqlResponse(array $weeks): ResponseInterface
+    {
+        $response = $this->createStub(ResponseInterface::class);
+        $response->method('toArray')->willReturn([
+            'data' => [
+                'user' => [
+                    'contributionsCollection' => [
+                        'contributionCalendar' => ['weeks' => $weeks],
+                    ],
+                ],
+            ],
+        ]);
+
+        return $response;
+    }
+
+    #[Test]
+    public function it_returns_github_as_name(): void
+    {
+        $this->assertSame('github', $this->makeProvider()->getName());
+    }
+
+    #[Test]
+    public function it_is_configured_when_credentials_are_set(): void
+    {
+        $this->assertTrue($this->makeProvider()->isConfigured());
+    }
+
+    #[Test]
+    public function it_is_not_configured_when_username_is_empty(): void
+    {
+        $this->assertFalse($this->makeProvider(username: '')->isConfigured());
+    }
+
+    #[Test]
+    public function it_is_not_configured_when_token_is_empty(): void
+    {
+        $this->assertFalse($this->makeProvider(token: '')->isConfigured());
+    }
+
+    #[Test]
+    public function it_parses_contribution_days_from_the_graphql_response(): void
+    {
+        $client = $this->createStub(HttpClientInterface::class);
+        $client->method('request')->willReturn($this->stubGraphqlResponse([
+            ['contributionDays' => [
+                ['date' => '2024-06-10', 'contributionCount' => 4],
+                ['date' => '2024-06-11', 'contributionCount' => 2],
+            ]],
+        ]));
+
+        $result = $this->makeProvider(client: $client)->fetch();
+
+        $this->assertSame(4, $result['2024-06-10']);
+        $this->assertSame(2, $result['2024-06-11']);
+    }
+
+    #[Test]
+    public function it_skips_days_with_zero_contributions(): void
+    {
+        $client = $this->createStub(HttpClientInterface::class);
+        $client->method('request')->willReturn($this->stubGraphqlResponse([
+            ['contributionDays' => [
+                ['date' => '2024-06-11', 'contributionCount' => 0],
+            ]],
+        ]));
+
+        $result = $this->makeProvider(client: $client)->fetch();
+
+        $this->assertArrayNotHasKey('2024-06-11', $result);
+    }
+
+    #[Test]
+    public function it_throws_service_unavailable_exception_on_graphql_errors(): void
+    {
+        $response = $this->createStub(ResponseInterface::class);
+        $response->method('toArray')->willReturn([
+            'errors' => [['message' => 'Bad credentials']],
+        ]);
+
+        $client = $this->createStub(HttpClientInterface::class);
+        $client->method('request')->willReturn($response);
+
+        $this->expectException(ServiceUnavailableHttpException::class);
+
+        $this->makeProvider(client: $client)->fetch();
+    }
+
+    #[Test]
+    public function it_returns_empty_when_response_has_no_weeks(): void
+    {
+        $client = $this->createStub(HttpClientInterface::class);
+        $client->method('request')->willReturn($this->stubGraphqlResponse([]));
+
+        $result = $this->makeProvider(client: $client)->fetch();
+
+        $this->assertSame([], $result);
+    }
+}
diff --git a/tests/Unit/Service/GitLabProviderTest.php b/tests/Unit/Service/GitLabProviderTest.php
new file mode 100644
index 0000000..5e09aa7
--- /dev/null
+++ b/tests/Unit/Service/GitLabProviderTest.php
@@ -0,0 +1,128 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Tests\Unit\Service;
+
+use App\Service\GitLabProvider;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\TestCase;
+use Psr\Log\LoggerInterface;
+use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;
+use Symfony\Contracts\HttpClient\HttpClientInterface;
+use Symfony\Contracts\HttpClient\ResponseInterface;
+
+#[CoversClass(GitLabProvider::class)]
+final class GitLabProviderTest extends TestCase
+{
+    private function makeProvider(
+        string $username = 'user',
+        string $token = 'token',
+        string $baseUrl = '',
+        ?HttpClientInterface $client = null,
+    ): GitLabProvider {
+        return new GitLabProvider(
+            $client ?? $this->createStub(HttpClientInterface::class),
+            $username,
+            $token,
+            $this->createStub(LoggerInterface::class),
+            $baseUrl,
+        );
+    }
+
+    private function stubResponse(array $data): ResponseInterface
+    {
+        $response = $this->createStub(ResponseInterface::class);
+        $response->method('toArray')->willReturn($data);
+
+        return $response;
+    }
+
+    #[Test]
+    public function it_returns_gitlab_as_name(): void
+    {
+        $this->assertSame('gitlab', $this->makeProvider()->getName());
+    }
+
+    #[Test]
+    public function it_is_configured_when_credentials_are_set(): void
+    {
+        $this->assertTrue($this->makeProvider()->isConfigured());
+    }
+
+    #[Test]
+    public function it_is_not_configured_when_username_is_empty(): void
+    {
+        $this->assertFalse($this->makeProvider(username: '')->isConfigured());
+    }
+
+    #[Test]
+    public function it_is_not_configured_when_token_is_empty(): void
+    {
+        $this->assertFalse($this->makeProvider(token: '')->isConfigured());
+    }
+
+    #[Test]
+    public function it_throws_not_found_exception_when_user_does_not_exist(): void
+    {
+        $client = $this->createStub(HttpClientInterface::class);
+        $client->method('request')->willReturn($this->stubResponse([]));
+
+        $this->expectException(NotFoundHttpException::class);
+
+        $this->makeProvider(client: $client)->fetch();
+    }
+
+    #[Test]
+    public function it_fetches_events_and_counts_them_by_date(): void
+    {
+        $client = $this->createMock(HttpClientInterface::class);
+        $client->method('request')->willReturnCallback(
+            function (string $method, string $url): ResponseInterface {
+                if (str_contains($url, '/events')) {
+                    return $this->stubResponse([
+                        ['created_at' => '2024-06-10T12:00:00.000Z'],
+                        ['created_at' => '2024-06-10T14:00:00.000Z'],
+                        ['created_at' => '2024-06-11T08:00:00.000Z'],
+                    ]);
+                }
+
+                return $this->stubResponse([['id' => 42]]);
+            }
+        );
+
+        $result = $this->makeProvider(client: $client)->fetch();
+
+        $this->assertSame(2, $result['2024-06-10']);
+        $this->assertSame(1, $result['2024-06-11']);
+    }
+
+    #[Test]
+    public function it_fetches_multiple_pages_until_page_has_fewer_than_100_events(): void
+    {
+        $callCount = 0;
+
+        $client = $this->createMock(HttpClientInterface::class);
+        $client->method('request')->willReturnCallback(
+            function (string $method, string $url) use (&$callCount): ResponseInterface {
+                if (!str_contains($url, '/events')) {
+                    return $this->stubResponse([['id' => 42]]);
+                }
+
+                $callCount++;
+                $data = $callCount === 1
+                    ? array_fill(0, 100, ['created_at' => '2024-06-10T12:00:00.000Z'])
+                    : [['created_at' => '2024-06-11T08:00:00.000Z']];
+
+                return $this->stubResponse($data);
+            }
+        );
+
+        $result = $this->makeProvider(client: $client)->fetch();
+
+        $this->assertSame(2, $callCount);
+        $this->assertSame(100, $result['2024-06-10']);
+        $this->assertSame(1, $result['2024-06-11']);
+    }
+}
diff --git a/tests/Unit/Service/GiteaProviderTest.php b/tests/Unit/Service/GiteaProviderTest.php
new file mode 100644
index 0000000..9593f29
--- /dev/null
+++ b/tests/Unit/Service/GiteaProviderTest.php
@@ -0,0 +1,111 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Tests\Unit\Service;
+
+use App\Service\GiteaProvider;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\TestCase;
+use Psr\Log\LoggerInterface;
+use Symfony\Contracts\HttpClient\HttpClientInterface;
+use Symfony\Contracts\HttpClient\ResponseInterface;
+
+#[CoversClass(GiteaProvider::class)]
+final class GiteaProviderTest extends TestCase
+{
+    private function makeProvider(
+        string $username = 'user',
+        string $token = 'token',
+        string $baseUrl = 'https://gitea.example.com',
+        ?HttpClientInterface $client = null,
+    ): GiteaProvider {
+        return new GiteaProvider(
+            $client ?? $this->createStub(HttpClientInterface::class),
+            $username,
+            $token,
+            $baseUrl,
+            $this->createStub(LoggerInterface::class),
+        );
+    }
+
+    private function stubResponse(array $data): ResponseInterface
+    {
+        $response = $this->createStub(ResponseInterface::class);
+        $response->method('toArray')->willReturn($data);
+
+        return $response;
+    }
+
+    #[Test]
+    public function it_returns_gitea_as_name(): void
+    {
+        $this->assertSame('gitea', $this->makeProvider()->getName());
+    }
+
+    #[Test]
+    public function it_is_configured_when_all_credentials_are_set(): void
+    {
+        $this->assertTrue($this->makeProvider()->isConfigured());
+    }
+
+    #[Test]
+    public function it_is_not_configured_when_username_is_empty(): void
+    {
+        $this->assertFalse($this->makeProvider(username: '')->isConfigured());
+    }
+
+    #[Test]
+    public function it_is_not_configured_when_token_is_empty(): void
+    {
+        $this->assertFalse($this->makeProvider(token: '')->isConfigured());
+    }
+
+    #[Test]
+    public function it_is_not_configured_when_base_url_is_empty(): void
+    {
+        $this->assertFalse($this->makeProvider(baseUrl: '')->isConfigured());
+    }
+
+    #[Test]
+    public function it_parses_heatmap_entries_into_contributions(): void
+    {
+        $now = time();
+
+        $client = $this->createStub(HttpClientInterface::class);
+        $client->method('request')->willReturn($this->stubResponse([
+            ['timestamp' => $now, 'contributions' => 5],
+        ]));
+
+        $result = $this->makeProvider(client: $client)->fetch();
+
+        $this->assertSame(5, $result[date('Y-m-d', $now)]);
+    }
+
+    #[Test]
+    public function it_filters_out_entries_older_than_365_days(): void
+    {
+        $old = (new \DateTimeImmutable('-366 days'))->getTimestamp();
+
+        $client = $this->createStub(HttpClientInterface::class);
+        $client->method('request')->willReturn($this->stubResponse([
+            ['timestamp' => $old, 'contributions' => 3],
+        ]));
+
+        $result = $this->makeProvider(client: $client)->fetch();
+
+        $this->assertSame([], $result);
+    }
+
+    #[Test]
+    public function it_returns_empty_when_response_has_no_entries(): void
+    {
+        $client = $this->createStub(HttpClientInterface::class);
+        $client->method('request')->willReturn($this->stubResponse([]));
+
+        $result = $this->makeProvider(client: $client)->fetch();
+
+        $this->assertSame([], $result);
+    }
+}
diff --git a/tests/Unit/Service/ProbeTraitTest.php b/tests/Unit/Service/ProbeTraitTest.php
new file mode 100644
index 0000000..64b5a28
--- /dev/null
+++ b/tests/Unit/Service/ProbeTraitTest.php
@@ -0,0 +1,128 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Tests\Unit\Service;
+
+use App\Service\ProbeTrait;
+use App\Service\ProviderErrorCode;
+use App\Service\ProviderInterface;
+use App\Service\ProviderStatusType;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\TestCase;
+use Symfony\Contracts\HttpClient\Exception\ClientExceptionInterface;
+use Symfony\Contracts\HttpClient\Exception\TransportExceptionInterface;
+use Symfony\Contracts\HttpClient\ResponseInterface;
+
+#[CoversClass(ProbeTrait::class)]
+final class ProbeTraitTest extends TestCase
+{
+    private function makeProvider(bool $configured, \Closure $ping): ProviderInterface
+    {
+        return new class($configured, $ping) implements ProviderInterface {
+            use ProbeTrait;
+
+            public function __construct(
+                private bool $configured,
+                private \Closure $ping,
+            ) {}
+
+            public function isConfigured(): bool { return $this->configured; }
+            public function getName(): string { return 'test'; }
+            public function ping(): void { ($this->ping)(); }
+            public function fetch(): array { return []; }
+        };
+    }
+
+    #[Test]
+    public function it_returns_not_configured_when_provider_is_not_configured(): void
+    {
+        $provider = $this->makeProvider(false, fn() => null);
+
+        $status = $provider->probe();
+
+        $this->assertSame(ProviderStatusType::NotConfigured, $status->status);
+        $this->assertNull($status->error);
+    }
+
+    #[Test]
+    public function it_returns_ok_when_ping_succeeds(): void
+    {
+        $provider = $this->makeProvider(true, fn() => null);
+
+        $status = $provider->probe();
+
+        $this->assertSame(ProviderStatusType::Ok, $status->status);
+        $this->assertNull($status->error);
+    }
+
+    #[Test]
+    public function it_returns_url_unreachable_on_transport_failure(): void
+    {
+        $exception = $this->createStub(TransportExceptionInterface::class);
+        $provider  = $this->makeProvider(true, fn() => throw $exception);
+
+        $status = $provider->probe();
+
+        $this->assertSame(ProviderStatusType::Error, $status->status);
+        $this->assertSame(ProviderErrorCode::UrlUnreachable, $status->error);
+    }
+
+    #[Test]
+    public function it_returns_auth_failed_on_401(): void
+    {
+        $response = $this->createStub(ResponseInterface::class);
+        $response->method('getStatusCode')->willReturn(401);
+
+        $exception = $this->createStub(ClientExceptionInterface::class);
+        $exception->method('getResponse')->willReturn($response);
+
+        $status = $this->makeProvider(true, fn() => throw $exception)->probe();
+
+        $this->assertSame(ProviderStatusType::Error, $status->status);
+        $this->assertSame(ProviderErrorCode::AuthFailed, $status->error);
+    }
+
+    #[Test]
+    public function it_returns_auth_failed_on_403(): void
+    {
+        $response = $this->createStub(ResponseInterface::class);
+        $response->method('getStatusCode')->willReturn(403);
+
+        $exception = $this->createStub(ClientExceptionInterface::class);
+        $exception->method('getResponse')->willReturn($response);
+
+        $status = $this->makeProvider(true, fn() => throw $exception)->probe();
+
+        $this->assertSame(ProviderStatusType::Error, $status->status);
+        $this->assertSame(ProviderErrorCode::AuthFailed, $status->error);
+    }
+
+    #[Test]
+    public function it_returns_url_unreachable_on_404(): void
+    {
+        $response = $this->createStub(ResponseInterface::class);
+        $response->method('getStatusCode')->willReturn(404);
+
+        $exception = $this->createStub(ClientExceptionInterface::class);
+        $exception->method('getResponse')->willReturn($response);
+
+        $status = $this->makeProvider(true, fn() => throw $exception)->probe();
+
+        $this->assertSame(ProviderStatusType::Error, $status->status);
+        $this->assertSame(ProviderErrorCode::UrlUnreachable, $status->error);
+    }
+
+    #[Test]
+    public function it_returns_unknown_error_on_unexpected_exception(): void
+    {
+        $provider = $this->makeProvider(true, fn() => throw new \RuntimeException('Something went wrong'));
+
+        $status = $provider->probe();
+
+        $this->assertSame(ProviderStatusType::Error, $status->status);
+        $this->assertSame(ProviderErrorCode::Unknown, $status->error);
+        $this->assertSame('Something went wrong', $status->message);
+    }
+}
diff --git a/tests/Unit/Service/ProviderHealthCheckerTest.php b/tests/Unit/Service/ProviderHealthCheckerTest.php
new file mode 100644
index 0000000..ebda929
--- /dev/null
+++ b/tests/Unit/Service/ProviderHealthCheckerTest.php
@@ -0,0 +1,88 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Tests\Unit\Service;
+
+use App\Service\ProviderErrorCode;
+use App\Service\ProviderHealthChecker;
+use App\Service\ProviderInterface;
+use App\Service\ProviderStatus;
+use App\Service\ProviderStatusType;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\TestCase;
+
+#[CoversClass(ProviderHealthChecker::class)]
+final class ProviderHealthCheckerTest extends TestCase
+{
+    #[Test]
+    public function it_returns_ok_when_all_providers_are_healthy(): void
+    {
+        $provider = $this->createStub(ProviderInterface::class);
+        $provider->method('probe')->willReturn(new ProviderStatus('test', ProviderStatusType::Ok));
+
+        $result = (new ProviderHealthChecker([$provider]))->check();
+
+        $this->assertSame('ok', $result['status']);
+    }
+
+    #[Test]
+    public function it_returns_degraded_when_a_provider_has_an_error(): void
+    {
+        $provider = $this->createStub(ProviderInterface::class);
+        $provider->method('probe')->willReturn(
+            new ProviderStatus('test', ProviderStatusType::Error, ProviderErrorCode::AuthFailed, 'Invalid token'),
+        );
+
+        $result = (new ProviderHealthChecker([$provider]))->check();
+
+        $this->assertSame('degraded', $result['status']);
+    }
+
+    #[Test]
+    public function it_does_not_degrade_when_a_provider_is_not_configured(): void
+    {
+        $provider = $this->createStub(ProviderInterface::class);
+        $provider->method('probe')->willReturn(new ProviderStatus('test', ProviderStatusType::NotConfigured));
+
+        $result = (new ProviderHealthChecker([$provider]))->check();
+
+        $this->assertSame('ok', $result['status']);
+    }
+
+    #[Test]
+    public function it_indexes_provider_statuses_by_name(): void
+    {
+        $provider = $this->createStub(ProviderInterface::class);
+        $provider->method('probe')->willReturn(new ProviderStatus('github', ProviderStatusType::Ok));
+
+        $result = (new ProviderHealthChecker([$provider]))->check();
+
+        $this->assertArrayHasKey('github', $result['providers']);
+    }
+
+    #[Test]
+    public function it_returns_ok_with_no_providers(): void
+    {
+        $result = (new ProviderHealthChecker([]))->check();
+
+        $this->assertSame('ok', $result['status']);
+        $this->assertSame([], $result['providers']);
+    }
+
+    #[Test]
+    public function it_includes_all_provider_statuses_in_output(): void
+    {
+        $github = $this->createStub(ProviderInterface::class);
+        $github->method('probe')->willReturn(new ProviderStatus('github', ProviderStatusType::Ok));
+
+        $gitlab = $this->createStub(ProviderInterface::class);
+        $gitlab->method('probe')->willReturn(new ProviderStatus('gitlab', ProviderStatusType::NotConfigured));
+
+        $result = (new ProviderHealthChecker([$github, $gitlab]))->check();
+
+        $this->assertArrayHasKey('github', $result['providers']);
+        $this->assertArrayHasKey('gitlab', $result['providers']);
+    }
+}
diff --git a/tests/Unit/Service/ProviderStatusTest.php b/tests/Unit/Service/ProviderStatusTest.php
new file mode 100644
index 0000000..9ff6119
--- /dev/null
+++ b/tests/Unit/Service/ProviderStatusTest.php
@@ -0,0 +1,64 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Tests\Unit\Service;
+
+use App\Service\ProviderErrorCode;
+use App\Service\ProviderStatus;
+use App\Service\ProviderStatusType;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\TestCase;
+
+#[CoversClass(ProviderStatus::class)]
+final class ProviderStatusTest extends TestCase
+{
+    #[Test]
+    public function it_serializes_ok_status(): void
+    {
+        $status = new ProviderStatus('github', ProviderStatusType::Ok);
+
+        $this->assertSame(['status' => 'ok'], $status->toArray());
+    }
+
+    #[Test]
+    public function it_serializes_not_configured_status(): void
+    {
+        $status = new ProviderStatus('github', ProviderStatusType::NotConfigured);
+
+        $this->assertSame(['status' => 'not_configured'], $status->toArray());
+    }
+
+    #[Test]
+    public function it_serializes_error_status_with_code_and_message(): void
+    {
+        $status = new ProviderStatus('github', ProviderStatusType::Error, ProviderErrorCode::AuthFailed, 'Token expired');
+
+        $this->assertSame([
+            'status'  => 'error',
+            'error'   => 'auth_failed',
+            'message' => 'Token expired',
+        ], $status->toArray());
+    }
+
+    #[Test]
+    public function it_omits_null_error_fields_from_array(): void
+    {
+        $status = new ProviderStatus('github', ProviderStatusType::Ok);
+
+        $array = $status->toArray();
+
+        $this->assertArrayNotHasKey('error', $array);
+        $this->assertArrayNotHasKey('message', $array);
+    }
+
+    #[Test]
+    public function it_exposes_typed_status_property(): void
+    {
+        $status = new ProviderStatus('github', ProviderStatusType::Error, ProviderErrorCode::Unknown, 'msg');
+
+        $this->assertSame(ProviderStatusType::Error, $status->status);
+        $this->assertSame(ProviderErrorCode::Unknown, $status->error);
+    }
+}

From a8d5f205db092b03fe2a684c1ad76b26be8b3dc3 Mon Sep 17 00:00:00 2001
From: ArthurErlich <a.erlich@live.de>
Date: Sat, 30 May 2026 14:14:38 +0200
Subject: [PATCH 14/15] docs: fix typos and reformat tables in CLAUDE.md

Fix "Prever" typo, add Windows WSL test runner command, and align
Markdown table columns for readability.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 CLAUDE.md | 41 ++++++++++++++++++++++++-----------------
 1 file changed, 24 insertions(+), 17 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 041db57..6e7769a 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -76,15 +76,16 @@ Run vendor/bin/phpunit after each change to confirm tests stay green.
 
 **Common anti-patterns**
 
-| Wrong prompt | Why it breaks TDD | Correct prompt |
-|---|---|---|
-| "Write tests for this feature" | Claude implements first, then fits tests to it | "Write **failing** tests for [feature]. Stop before any implementation." |
-| "Add tests and implementation" | Loses the design feedback of failing tests | Two separate prompts: Red, then Green |
-| "Make the tests pass" | Encourages skipping to a green state | "Implement the minimum to make the failing tests pass." |
-| Combining Red + Green in one request | No failing baseline | Always separate the two phases |
+| Wrong prompt                         | Why it breaks TDD                              | Correct prompt                                                           |
+| ------------------------------------ | ---------------------------------------------- | ------------------------------------------------------------------------ |
+| "Write tests for this feature"       | Claude implements first, then fits tests to it | "Write **failing** tests for [feature]. Stop before any implementation." |
+| "Add tests and implementation"       | Loses the design feedback of failing tests     | Two separate prompts: Red, then Green                                    |
+| "Make the tests pass"                | Encourages skipping to a green state           | "Implement the minimum to make the failing tests pass."                  |
+| Combining Red + Green in one request | No failing baseline                            | Always separate the two phases                                           |
 
 ### Running tests
-Prever to use the tests in `docker compose exec graph`
+
+Prefer to use the tests in `docker compose exec graph`
 
 ```bash
 # Run full suite
@@ -100,6 +101,12 @@ vendor/bin/phpunit tests/Unit/Service/SvgRendererTest.php
 vendor/bin/phpunit --filter it_renders
 ```
 
+On Windows, run via WSL (If Docker Desctop is not):
+
+```powershell
+wsl -e bash -c "cd /mnt/g/_DEV/repos/git-contribution-graph && docker compose exec graph vendor/bin/phpunit --testdox 2>&1"
+```
+
 ### Auto-run hook
 
 Add to `.claude/settings.json` to run PHPUnit automatically after every file edit:
@@ -131,8 +138,8 @@ Workflow files live in [.gitea/workflows/](.gitea/workflows/). This project uses
 
 **Current workflows:**
 
-| File | Trigger | Purpose |
-|---|---|---|
+| File                 | Trigger          | Purpose                                                   |
+| -------------------- | ---------------- | --------------------------------------------------------- |
 | `docker-publish.yml` | Push tag `*.*.*` | Build & push multi-arch image to Gitea container registry |
 
 ## Docker
@@ -209,13 +216,13 @@ GET /graph.svg?theme=dark|light
 
 ## Environment variables
 
-| Variable | Required | Notes |
-|---|---|---|
-| `APP_SECRET` | Yes | 32+ char random string |
-| `GITHUB_USER` / `GITHUB_TOKEN` | For GitHub | Token scope: `read:user` |
-| `GITLAB_USER` / `GITLAB_TOKEN` | For GitLab | Token scopes: `read_user`, `read_api` |
-| `GITLAB_URL` | No | Defaults to `https://gitlab.com` |
-| `GITEA_USER` / `GITEA_TOKEN` / `GITEA_URL` | For Gitea | Token scope: `read:user` |
-| `ALLOWED_HOSTS` | No | Comma-separated hostnames; empty = allow all |
+| Variable                                   | Required   | Notes                                        |
+| ------------------------------------------ | ---------- | -------------------------------------------- |
+| `APP_SECRET`                               | Yes        | 32+ char random string                       |
+| `GITHUB_USER` / `GITHUB_TOKEN`             | For GitHub | Token scope: `read:user`                     |
+| `GITLAB_USER` / `GITLAB_TOKEN`             | For GitLab | Token scopes: `read_user`, `read_api`        |
+| `GITLAB_URL`                               | No         | Defaults to `https://gitlab.com`             |
+| `GITEA_USER` / `GITEA_TOKEN` / `GITEA_URL` | For Gitea  | Token scope: `read:user`                     |
+| `ALLOWED_HOSTS`                            | No         | Comma-separated hostnames; empty = allow all |
 
 Copy `.env` to `.env.local` for local development — `.env.local` is gitignored.

From 38312f549c6d440ee0124adf7403b6c345d2c092 Mon Sep 17 00:00:00 2001
From: ArthurErlich <a.erlich@live.de>
Date: Sat, 30 May 2026 14:27:58 +0200
Subject: [PATCH 15/15] docs: add CHANGELOG for 0.1.0

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 CHANGELOG.md | 47 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 47 insertions(+)
 create mode 100644 CHANGELOG.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..6665ec2
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,47 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-05-30
+
+### Added
+
+- **FrankenPHP runtime** — base image migrated from `php-cli` to FrankenPHP Alpine for better performance and built-in web server support
+- **FrankenPHP worker mode** — Symfony worker script (`public/worker.php`) with request reuse and graceful reload
+- **Caddy configuration** — `docker/frankenphp/Caddyfile` and `Caddyfile.dev` for production and development setups
+- **Provider health probes** — `ProviderInterface` extended with `ping()` and `probe()` methods; `ProbeTrait` provides the shared implementation
+- **Per-provider status on `/health`** — the health endpoint now reports `ok`, `degraded`, or `down` for each configured provider (GitHub, GitLab, Gitea), along with an error code and latency
+- **Supporting value objects** — `ProviderStatus`, `ProviderStatusType`, `ProviderErrorCode`, and `ProviderHealthChecker` service
+- **`ContributionAggregator` service** — contribution merging logic extracted from `GraphController` into a dedicated, testable service
+
+### Fixed
+
+- Optional environment variables (`GITLAB_URL`, `ALLOWED_HOSTS`, etc.) now have explicit empty default values in `docker-compose.yml`, preventing Docker Compose warnings on startup
+
+### Changed
+
+- `SvgRenderer` is now `final` and declares `strict_types=1`
+
+### Tests
+
+- Unit tests added for `ProbeTrait`, `ProviderHealthChecker`, `ProviderStatus`, `ContributionAggregator`, and all three provider probes (`GitHubProvider`, `GitLabProvider`, `GiteaProvider`)
+- `SvgRendererTest` refactored to follow project PHPUnit conventions (`#[Test]` attribute, `it_` prefix, Arrange/Act/Assert structure)
+
+## [0.0.1] - 2025-01-01
+
+### Added
+
+- Initial release — GitHub, GitLab, and Gitea contribution graph as a self-hosted SVG endpoint
+- Light and dark theme support
+- Filesystem cache with 1-hour TTL
+- Docker multi-stage build (`base → deps → build → final`)
+- Basic `/health` endpoint
+
+[Unreleased]: https://github.com/ArthurErlich/git-contribution-graph/compare/0.1.0...HEAD
+[0.1.0]: https://github.com/ArthurErlich/git-contribution-graph/compare/0.0.1...0.1.0
+[0.0.1]: https://github.com/ArthurErlich/git-contribution-graph/releases/tag/0.0.1