fix: primary address saving

Signed-off-by: Sebastian Krupinski <krupinski01@gmail.com>

.github/workflows/build-test.yml

@@ -0,0 +1,50 @@
+name: Build Test
+
+on:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Retrieve Server Install Action
+        uses: actions/checkout@v6.0.2
+        with:
+          repository: Nodarx/action-server-install
+          ref: main
+          path: action-server-install
+          github-server-url: https://git.ktrix.dev
+
+      - name: Install Server
+        uses: ./action-server-install
+        with:
+          install-php: 'false'
+          install-node: 'true'
+          php-version: '8.5'
+          node-version: '24'
+          server-path: './server'
+
+      - name: Install Mail Manager
+        uses: actions/checkout@v6.0.2
+        with:
+          repository: Nodarx/mail_manager
+          ref: main
+          path: server/modules/mail_manager
+          github-server-url: https://git.ktrix.dev
+
+      - name: Checkout Pull Request
+        uses: actions/checkout@v6.0.2
+        with:
+          repository: ${{ github.repository }}
+          ref: ${{ github.event.pull_request.head.sha }}
+          path: server/modules/provider_imap
+          github-server-url: https://git.ktrix.dev
+
+      - name: Install dependencies
+        run: npm ci
+        working-directory: server/modules/provider_imap
+
+      - name: Build
+        run: npm run build
+        working-directory: server/modules/provider_imap

.github/workflows/js-unit-tests.yml

@@ -0,0 +1,50 @@
+name: JS Unit Tests
+
+on:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Retrieve Server Install Action
+        uses: actions/checkout@v6.0.2
+        with:
+          repository: Nodarx/action-server-install
+          ref: main
+          path: action-server-install
+          github-server-url: https://git.ktrix.dev
+
+      - name: Install Server
+        uses: ./action-server-install
+        with:
+          install-php: 'false'
+          install-node: 'true'
+          php-version: '8.5'
+          node-version: '24'
+          server-path: './server'
+
+      - name: Install Mail Manager
+        uses: actions/checkout@v6.0.2
+        with:
+          repository: Nodarx/mail_manager
+          ref: main
+          path: server/modules/mail_manager
+          github-server-url: https://git.ktrix.dev
+
+      - name: Checkout Pull Request
+        uses: actions/checkout@v6.0.2
+        with:
+          repository: ${{ github.repository }}
+          ref: ${{ github.event.pull_request.head.sha }}
+          path: server/modules/provider_imap
+          github-server-url: https://git.ktrix.dev
+
+      - name: Install dependencies
+        run: npm ci
+        working-directory: server/modules/provider_imap
+
+      - name: Run tests
+        run: npm run test:unit
+        working-directory: server/modules/provider_imap

.github/workflows/php-integration-tests.yml

@@ -0,0 +1,59 @@
+name: PHP Integration Tests
+
+on:
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  test:
+    name: Integration Tests
+    runs-on: ubuntu-latest
+    services:
+      mongo:
+        image: mongo:8
+        options: >-
+          --health-cmd "mongosh --quiet --eval \"db.adminCommand('ping')\""
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 12
+
+    steps:
+      - name: Retrieve Server Install Action
+        uses: actions/checkout@v6.0.2
+        with:
+          repository: Nodarx/action-server-install
+          ref: main
+          path: action-server-install
+          github-server-url: https://git.ktrix.dev
+
+      - name: Install server
+        uses: ./action-server-install
+        with:
+          install-php: 'true'
+          php-version: '8.5'
+          server-path: './server'
+          database-uri: 'mongodb://mongo:27017/?tls=false'
+          database-name: 'ktrix_ci'
+          app-environment: 'test'
+
+      - name: Checkout module under test
+        uses: actions/checkout@v6.0.2
+        with:
+          repository: ${{ github.repository }}
+          ref: ${{ github.event.pull_request.head.sha || github.sha }}
+          path: server/modules/provider_imap
+          github-server-url: https://git.ktrix.dev
+
+      - name: Install module dependencies
+        run: composer install --prefer-dist --no-progress
+        working-directory: server/modules/provider_imap
+
+      - name: Install and enable module
+        working-directory: server
+        run: |
+          php bin/console module:install provider_imap
+          php bin/console module:enable provider_imap
+
+      - name: Run integration tests
+        working-directory: server/modules/provider_imap
+        run: composer test:integration

.github/workflows/php-unit-tests.yml

@@ -0,0 +1,42 @@
+name: PHP Unit Tests
+
+on:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Retrieve Server Install Action
+        uses: actions/checkout@v6.0.2
+        with:
+          repository: Nodarx/action-server-install
+          ref: main
+          path: action-server-install
+          github-server-url: https://git.ktrix.dev
+
+      - name: Install Server
+        uses: ./action-server-install
+        with:
+          install-php: 'true'
+          install-node: 'false'
+          php-version: '8.5'
+          node-version: '24'
+          server-path: './server'
+
+      - name: Checkout Pull Request
+        uses: actions/checkout@v6.0.2
+        with:
+          repository: ${{ github.repository }}
+          ref: ${{ github.event.pull_request.head.sha }}
+          path: server/modules/provider_imap
+          github-server-url: https://git.ktrix.dev
+
+      - name: Install dependencies
+        run: composer install --prefer-dist --no-progress
+        working-directory: server/modules/provider_imap
+
+      - name: Run tests
+        run: composer test:unit
+        working-directory: server/modules/provider_imap

.github/workflows/renovate.yml

@@ -25,11 +25,17 @@ jobs:
           tools: composer:v2
 
       - name: Install Renovate
-        run: npm install -g renovate
+        run: |
+          npm install --global --no-audit --fund=false \
+            --prefix "${{ runner.temp }}/renovate-npm" \
+            --cache "${{ runner.temp }}/renovate-npm-cache" \
+            renovate
+          "${{ runner.temp }}/renovate-npm/bin/renovate" --version
 
       - name: Run Renovate
         env:
           RENOVATE_TOKEN: ${{ secrets.RENOVATE_TOKEN }}
           RENOVATE_PLATFORM: gitea
           RENOVATE_ENDPOINT: https://git.ktrix.dev/api/v1
-        run: renovate ${{ gitea.repository }}
+        run: |
+          "${{ runner.temp }}/renovate-npm/bin/renovate" ${{ gitea.repository }}

.gitignore

@@ -14,11 +14,7 @@ node_modules/
 # Backend development
 /lib/vendor/
 coverage/
-phpunit.xml.cache
-.phpunit.cache
-.phpunit.result.cache
-.php-cs-fixer.cache
-.phpstan.cache
+*.cache
 .phpactor/
 
 # Editors

composer.json

@@ -7,7 +7,7 @@
   "config": {
     "optimize-autoloader": true,
     "platform": {
-      "php": "8.2"
+      "php": "8.3"
     },
     "autoloader-suffix": "ProviderImap",
     "vendor-dir": "lib/vendor",
@@ -16,16 +16,16 @@
     }
   },
   "require": {
-    "php": ">=8.2 <=8.5",
+    "php": ">=8.3 <=8.5",
     "ext-iconv": "*",
     "ext-ctype": "*",
     "psr/log": "^1.0|^2.0|^3.0",
     "doctrine/lexer": "^3.0",
-    "symfony/mime": "^8.0",
+    "symfony/mime": "^7.0",
     "egulias/email-validator": "^4.0"
   },
   "require-dev": {
-    "phpunit/phpunit": "^11.0"
+    "phpunit/phpunit": "^12.0"
   },
   "autoload": {
     "psr-4": {
@@ -34,7 +34,7 @@
   },
   "autoload-dev": {
       "psr-4": {
-          "KTXM\\ProviderImap\\": "tests/php/"
+          "KTXT\\ProviderImap\\Tests\\": "tests/php/"
       }
   },
   "scripts": {
@@ -42,7 +42,8 @@
       ],
       "post-update-cmd": [
       ],
-      "test:unit": "phpunit --configuration tests/php/phpunit.unit.xml --colors=always --testdox",
-      "test:coverage": "XDEBUG_MODE=coverage phpunit --configuration tests/php/phpunit.unit.xml --coverage-html .phpunit.coverage --coverage-text"
+      "test:unit": "phpunit --configuration tests/php/phpunit.xml --testsuite \"Unit Tests\" --colors=always --testdox",
+      "test:integration": "phpunit --configuration tests/php/phpunit.xml --testsuite \"Integration Tests\" --colors=always --testdox",
+      "test:coverage": "XDEBUG_MODE=coverage phpunit --configuration tests/php/phpunit.xml --testsuite \"Unit Tests\" --coverage-html .phpunit.coverage --coverage-text"
   }
 }

lib/Client/Command/FetchResponseParser.php

@@ -39,7 +39,7 @@ final class FetchResponseParser
     public function parseMany(ResponseStream $responses): Generator
     {
         foreach ($responses as $response) {
-            if ($response instanceof UntaggedResponse && MessageParser::isFetchMessage($response->payload())) {
+            if ($response instanceof UntaggedResponse && MessageParser::isFetchMessage($response->raw())) {
                 yield MessageParser::parse($response->raw());
                 continue;
             }
@@ -55,4 +55,4 @@ final class FetchResponseParser
 
         throw new ImapException('FETCH did not receive a tagged completion response.');
     }
-}
+}

lib/Client/MessageParser.php

@@ -8,19 +8,21 @@ use DateTimeInterface;
 
 final class MessageParser
 {
-    public static function isFetchMessage(string $payload): bool
+    public static function isFetchMessage(string $raw): bool
     {
-        return str_contains(strtoupper($payload), 'FETCH (');
+        return preg_match('/^\*\s+\d+\s+FETCH\s+\(/i', $raw) === 1;
     }
 
     public static function parse(string $raw): Message
     {
-        if (!preg_match('/^\*\s+(\d+)\s+FETCH\s+\((.*)\)$/is', $raw, $matches)) {
+        if (preg_match('/^\*\s+(\d+)\s+FETCH\s+\(/iA', $raw, $matches) !== 1
+            || !str_ends_with($raw, ')')) {
             throw new ImapException('Unable to parse FETCH response: ' . $raw);
         }
 
         $sequence = (int) $matches[1];
-        $attributes = self::parseAttributes($matches[2]);
+        $offset = strlen($matches[0]);
+        $attributes = self::parseAttributes($raw, $offset, strlen($raw) - 1);
         $uid = self::toInt($attributes['UID'] ?? null, 'FETCH response is missing UID: ' . $raw);
         $envelope = is_array($attributes['ENVELOPE'] ?? null) ? $attributes['ENVELOPE'] : null;
         $bodyStructure = isset($attributes['BODYSTRUCTURE']) ? self::parseBodyPart($attributes['BODYSTRUCTURE'], '') : null;
@@ -52,15 +54,13 @@ final class MessageParser
     /**
      * @return array<string, mixed>
      */
-    private static function parseAttributes(string $payload): array
+    private static function parseAttributes(string $payload, int &$offset, int $end): array
     {
         $attributes = [];
-        $offset = 0;
-        $length = strlen($payload);
 
-        while ($offset < $length) {
+        while ($offset < $end) {
             self::skipWhitespace($payload, $offset);
-            if ($offset >= $length) {
+            if ($offset >= $end) {
                 break;
             }
 
@@ -784,4 +784,4 @@ final class MessageParser
             $value,
         )));
     }
-}
+}

lib/Client/Protocol/ProtocolReader.php

@@ -56,16 +56,27 @@ final class ProtocolReader
         }
 
         if (str_starts_with($raw, '* ')) {
-            $parts = preg_split('/\s+/', substr($raw, 2), 2) ?: [];
-            $label = strtoupper($parts[0] ?? '');
+            // Keep the payload as a slice of the raw response. FETCH payloads can
+            // contain large message literals, so eagerly splitting here would keep
+            // a second full copy alive while the message is parsed.
+            $labelEnd = 2;
+            while (isset($raw[$labelEnd]) && !ctype_space($raw[$labelEnd])) {
+                $labelEnd++;
+            }
+            $label = strtoupper(substr($raw, 2, $labelEnd - 2));
+            $payloadOffset = $labelEnd;
+            while (isset($raw[$payloadOffset]) && ctype_space($raw[$payloadOffset])) {
+                $payloadOffset++;
+            }
             $this->logger?->debug('IMAP untagged response received: {raw}', [
                 'label' => $label,
                 'raw' => $raw,
             ]);
             return new UntaggedResponse(
                 $label,
-                $parts[1] ?? '',
+                '',
                 $raw,
+                $payloadOffset,
             );
         }
 
@@ -181,4 +192,4 @@ final class ProtocolReader
 
         return $raw;
     }
-}
+}

lib/Client/Protocol/Response/UntaggedResponse.php

@@ -10,6 +10,7 @@ final class UntaggedResponse implements ResponseInterface
         private readonly string $label,
         private readonly string $payload,
         private readonly string $raw,
+        private readonly ?int $payloadOffset = null,
     ) {}
 
     public function label(): string
@@ -19,6 +20,12 @@ final class UntaggedResponse implements ResponseInterface
 
     public function payload(): string
     {
+        // ProtocolReader records an offset for potentially large responses and
+        // only materializes the payload for command parsers that actually need it.
+        if ($this->payloadOffset !== null) {
+            return substr($this->raw, $this->payloadOffset);
+        }
+
         return $this->payload;
     }
 
@@ -27,7 +34,7 @@ final class UntaggedResponse implements ResponseInterface
      */
     public function payloadTokens(): array
     {
-        $payload = trim($this->payload);
+        $payload = trim($this->payload());
 
         if ($payload === '') {
             return [];
@@ -40,4 +47,4 @@ final class UntaggedResponse implements ResponseInterface
     {
         return $this->raw;
     }
-}
+}

lib/Console/ConnectCommand.php

@@ -13,7 +13,7 @@ use KTXM\ProviderImap\Providers\Provider;
 use KTXM\ProviderImap\Providers\Service;
 use KTXM\ProviderImap\Providers\ServiceIdentityBasic;
 use KTXM\ProviderImap\Providers\ServiceLocation;
-use KTXC\SessionTenant;
+use KTXC\Context\TenantContext;
 use Symfony\Component\Console\Attribute\AsCommand;
 use Symfony\Component\Console\Command\Command;
 use Symfony\Component\Console\Input\InputArgument;
@@ -41,7 +41,7 @@ class ConnectCommand extends Command
 {
     public function __construct(
         private readonly Provider      $provider,
-        private readonly SessionTenant $sessionTenant,
+        private readonly TenantContext $tenantContext,
     ) {
         parent::__construct();
     }
@@ -186,7 +186,7 @@ class ConnectCommand extends Command
 
         // ── Persist ──────────────────────────────────────────────────────────
 
-        $this->sessionTenant->configureById($tenantId);
+        $this->tenantContext->resolveIdentifier($tenantId);
 
         $label = $io->ask('Service label', $username);
         if ($label) {

lib/Console/DisconnectCommand.php

@@ -11,7 +11,7 @@ namespace KTXM\ProviderImap\Console;
 
 use KTXM\ProviderImap\Providers\Provider;
 use KTXM\ProviderImap\Providers\Service;
-use KTXC\SessionTenant;
+use KTXC\Context\TenantContext;
 use Symfony\Component\Console\Attribute\AsCommand;
 use Symfony\Component\Console\Command\Command;
 use Symfony\Component\Console\Input\InputArgument;
@@ -37,7 +37,7 @@ class DisconnectCommand extends Command
 {
     public function __construct(
         private readonly Provider      $provider,
-        private readonly SessionTenant $sessionTenant,
+        private readonly TenantContext $tenantContext,
     ) {
         parent::__construct();
     }
@@ -86,7 +86,7 @@ class DisconnectCommand extends Command
             $userId   = (string) ($input->getOption('user') ?? '');
 
             if ($tenantId !== '' && $userId !== '') {
-                $this->sessionTenant->configureById($tenantId);
+                $this->tenantContext->resolveIdentifier($tenantId);
                 $services = $this->provider->serviceList($tenantId, $userId);
 
                 if (empty($services)) {
@@ -130,7 +130,7 @@ class DisconnectCommand extends Command
         }
 
         // ── Fetch service for display ────────────────────────────────────────
-        $this->sessionTenant->configureById($tenantId);
+        $this->tenantContext->resolveIdentifier($tenantId);
         $service = $this->provider->serviceFetch($tenantId, $userId, $serviceId);
 
         if ($service === null) {

lib/Console/DiscoverCommand.php

@@ -14,7 +14,7 @@ use KTXM\ProviderImap\Providers\Service;
 use KTXM\ProviderImap\Providers\ServiceIdentityBasic;
 use KTXM\ProviderImap\Providers\ServiceLocation;
 use KTXM\ProviderImap\Service\Discovery;
-use KTXC\SessionTenant;
+use KTXC\Context\TenantContext;
 use Symfony\Component\Console\Attribute\AsCommand;
 use Symfony\Component\Console\Command\Command;
 use Symfony\Component\Console\Input\InputArgument;
@@ -43,7 +43,7 @@ class DiscoverCommand extends Command
     public function __construct(
         private readonly Provider      $provider,
         private readonly Discovery     $discovery,
-        private readonly SessionTenant $sessionTenant,
+        private readonly TenantContext $tenantContext,
     ) {
         parent::__construct();
     }
@@ -210,7 +210,7 @@ class DiscoverCommand extends Command
 
         // ── Persist ──────────────────────────────────────────────────────────
 
-        $this->sessionTenant->configureById($tenantId);
+        $this->tenantContext->resolveIdentifier($tenantId);
 
         $label = $io->ask('Service label', $address);
         if ($label) {

lib/Console/TestCommand.php

@@ -9,7 +9,7 @@ declare(strict_types=1);
 
 namespace KTXM\ProviderImap\Console;
 
-use KTXC\SessionTenant;
+use KTXC\Context\TenantContext;
 use KTXM\ProviderImap\Client\Command\SelectCommand;
 use KTXM\ProviderImap\Client\FetchOptions;
 use KTXM\ProviderImap\Client\FetchTarget;
@@ -41,7 +41,7 @@ class TestCommand extends Command
 {
     public function __construct(
         private readonly Provider $provider,
-        private readonly SessionTenant $sessionTenant,
+        private readonly TenantContext $tenantContext,
     ) {
         parent::__construct();
     }
@@ -108,7 +108,7 @@ class TestCommand extends Command
             return Command::FAILURE;
         }
 
-        $this->sessionTenant->configureById($tenantId);
+        $this->tenantContext->resolveIdentifier($tenantId);
         $service = $this->provider->serviceFetch($tenantId, $userId, $serviceId);
 
         if ($service === null) {
@@ -269,7 +269,7 @@ class TestCommand extends Command
             return;
         }
 
-        $this->sessionTenant->configureById($tenantId);
+        $this->tenantContext->resolveIdentifier($tenantId);
         $services = $this->provider->serviceList($tenantId, $userId);
 
         if ($services === []) {

lib/Providers/Service.php

@@ -200,8 +200,9 @@ class Service implements ServiceBaseInterface, ServiceMutableInterface, ServiceC
         if (isset($data[self::PROPERTY_IDENTITY])) {
             $this->setIdentity($this->freshIdentity(null, $data[self::PROPERTY_IDENTITY]));
         }
-        if (isset($data[self::PROPERTY_PRIMARY_ADDRESS]) && is_string($data[self::PROPERTY_PRIMARY_ADDRESS])) {
-            $this->setPrimaryAddress(new Address($data[self::PROPERTY_PRIMARY_ADDRESS]));
+        if (isset($data[self::PROPERTY_PRIMARY_ADDRESS])) {
+            $value = $data[self::PROPERTY_PRIMARY_ADDRESS];
+            $this->setPrimaryAddress(is_array($value) ? Address::fromArray($value) : new Address((string)$value));
         }
         if (isset($data[self::PROPERTY_SECONDARY_ADDRESSES]) && is_array($data[self::PROPERTY_SECONDARY_ADDRESSES])) {
             $this->setSecondaryAddresses(array_map(

lib/Service/Remote/RemoteMailService.php

@@ -11,7 +11,6 @@ namespace KTXM\ProviderImap\Service\Remote;
 
 use DateTimeImmutable;
 use Generator;
-use KTXC\Server;
 use KTXC\Logger\PlainFileLogger;
 use KTXM\ProviderImap\Client\Client as ImapClient;
 use KTXM\ProviderImap\Client\Command\AppendCommand;
@@ -132,7 +131,7 @@ class RemoteMailService
             return null;
         }
 
-        $logDir = Server::getInstance()?->logDir() ?? __DIR__ . '/../../../../../var/log';
+        $logDir = dirname(__DIR__, 5) . '/var/log';
 
         return new PlainFileLogger($logDir . '/' . $channel, $this->service->identifier());
     }

package.json

@@ -11,7 +11,11 @@
     "dev": "vite build --mode development --config vite.config.ts",
     "watch": "vite build --mode development --watch --config vite.config.ts",
     "typecheck": "vue-tsc --noEmit",
-    "lint": "eslint . --ext .vue,.js,.jsx,.cjs,.mjs,.ts,.tsx,.cts,.mts --fix --ignore-path .gitignore"
+    "lint": "eslint . --ext .vue,.js,.jsx,.cjs,.mjs,.ts,.tsx,.cts,.mts --fix --ignore-path .gitignore",
+    "test": "vitest run --config tests/js/vitest.config.ts",
+    "test:unit": "vitest run --config tests/js/vitest.config.ts",
+    "test:watch": "vitest watch --config tests/js/vitest.config.ts",
+    "test:coverage": "vitest run --coverage --config tests/js/vitest.config.ts"
   },
   "dependencies": {
     "pinia": "^3.0.0",
@@ -24,6 +28,10 @@
     "@vue/tsconfig": "^0.9.0",
     "typescript": "~6.0.0",
     "vite": "^8.0.0",
-    "vue-tsc": "^3.0.5"
+    "vue-tsc": "^3.0.5",
+    "@vitest/coverage-v8": "^4.1.6",
+    "@vue/test-utils": "^2.4.10",
+    "jsdom": "^29.1.1",
+    "vitest": "^4.1.6"
   }
-}
+}

src/components/ImapAuthPanel.vue

@@ -115,7 +115,7 @@ function sameIdentity(a: ServiceIdentity | null, b: ServiceIdentity | null): boo
       variant="outlined"
       prepend-inner-icon="mdi-account"
       class="mb-4"
-      autocomplete="username"
+      autocomplete="off"
       autocorrect="off"
       autocapitalize="none"
       :rules="[rules.required]"
@@ -130,7 +130,7 @@ function sameIdentity(a: ServiceIdentity | null, b: ServiceIdentity | null): boo
       variant="outlined"
       prepend-inner-icon="mdi-lock"
       class="mb-4"
-      autocomplete="current-password"
+      autocomplete="new-password"
       :rules="[rules.required]"
     />
   </div>

tests/js/unit/base.test.ts

@@ -0,0 +1,30 @@
+import { describe, it, expect } from 'vitest'
+
+describe('Basic Tests', () => {
+  it('should perform basic assertion', () => {
+    expect(true).toBe(true)
+  })
+
+  it('should test array operations', () => {
+    const array = ['foo', 'bar', 'baz']
+
+    expect(array).toHaveLength(3)
+    expect(array).toContain('bar')
+    expect(array[0]).toBe('foo')
+  })
+
+  it('should test string operations', () => {
+    const string = 'Hello, World!'
+
+    expect(string).toContain('World')
+    expect(string.length).toBe(13)
+  })
+
+  it('should test object operations', () => {
+    const obj = { foo: 'bar', count: 42 }
+
+    expect(obj).toHaveProperty('foo')
+    expect(obj.foo).toBe('bar')
+    expect(obj.count).toBeGreaterThan(40)
+  })
+})

tests/js/vitest.config.ts

@@ -0,0 +1,33 @@
+import { fileURLToPath } from 'node:url'
+import { defineConfig, configDefaults } from 'vitest/config'
+import vue from '@vitejs/plugin-vue'
+import path from 'path'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+
+export default defineConfig({
+  plugins: [vue()],
+  resolve: {
+    alias: {
+      '@': path.resolve(__dirname, '../../src'),
+      '@KTXC': path.resolve(__dirname, '../../../../core/src'),
+    },
+  },
+  test: {
+    environment: 'jsdom',
+    exclude: [...configDefaults.exclude, 'e2e/**'],
+    root: fileURLToPath(new URL('../../', import.meta.url)),
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html'],
+      exclude: [
+        'node_modules/',
+        'tests/',
+        '**/*.d.ts',
+        '**/*.config.*',
+        '**/dist/**',
+      ],
+    },
+  },
+})

tests/php/Integration/BaseTest.php

@@ -0,0 +1,29 @@
+<?php
+
+namespace KTXT\ProviderImap\Tests\Integration;
+
+use PHPUnit\Framework\TestCase;
+
+class BaseTest extends TestCase
+{
+    public function testBasicAssertion(): void
+    {
+        $this->assertTrue(true);
+    }
+
+    public function testArrayOperations(): void
+    {
+        $array = ['foo' => 'bar'];
+
+        $this->assertArrayHasKey('foo', $array);
+        $this->assertEquals('bar', $array['foo']);
+    }
+
+    public function testStringOperations(): void
+    {
+        $string = 'Hello, World!';
+
+        $this->assertStringContainsString('World', $string);
+        $this->assertEquals(13, strlen($string));
+    }
+}

tests/php/Unit/BaseTest.php

@@ -0,0 +1,29 @@
+<?php
+
+namespace KTXT\ProviderImap\Tests\Unit;
+
+use PHPUnit\Framework\TestCase;
+
+class BaseTest extends TestCase
+{
+    public function testBasicAssertion(): void
+    {
+        $this->assertTrue(true);
+    }
+
+    public function testArrayOperations(): void
+    {
+        $array = ['foo' => 'bar'];
+
+        $this->assertArrayHasKey('foo', $array);
+        $this->assertEquals('bar', $array['foo']);
+    }
+
+    public function testStringOperations(): void
+    {
+        $string = 'Hello, World!';
+
+        $this->assertStringContainsString('World', $string);
+        $this->assertEquals(13, strlen($string));
+    }
+}

tests/php/bootstrap.php

@@ -0,0 +1,17 @@
+<?php
+
+require dirname(__DIR__, 2).'/lib/vendor/autoload.php';
+
+// When this module is checked out inside a full server (server/modules/<handle>,
+// as it is in CI and in this monorepo checkout), also load the server's own
+// core/shared autoloader so tests can reference framework (KTXC/KTXF) types.
+// Standalone module checkouts without a server alongside them skip this.
+define('SERVER_ROOT', dirname(__DIR__, 4));
+$serverAutoload = SERVER_ROOT . '/vendor/autoload.php';
+if (is_file($serverAutoload)) {
+    require $serverAutoload;
+}
+
+if (isset($_SERVER['APP_DEBUG']) && $_SERVER['APP_DEBUG']) {
+    umask(0000);
+}

tests/php/phpunit.xml

@@ -0,0 +1,41 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!-- https://phpunit.readthedocs.io/en/latest/configuration.html -->
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:noNamespaceSchemaLocation="../../lib/vendor/phpunit/phpunit/phpunit.xsd"
+         colors="true"
+         failOnDeprecation="true"
+         failOnNotice="true"
+         failOnWarning="true"
+         bootstrap="bootstrap.php"
+         cacheDirectory="../../.phpunit.cache"
+>
+    <php>
+        <ini name="display_errors" value="1" />
+        <ini name="error_reporting" value="-1" />
+        <server name="APP_ENV" value="test" force="true" />
+        <server name="SHELL_VERBOSITY" value="-1" />
+    </php>
+
+    <testsuites>
+        <testsuite name="Unit Tests">
+            <directory>Unit</directory>
+        </testsuite>
+        <testsuite name="Integration Tests">
+            <directory>Integration</directory>
+        </testsuite>
+    </testsuites>
+
+    <source ignoreSuppressionOfDeprecations="true"
+            ignoreIndirectDeprecations="true"
+            restrictNotices="true"
+            restrictWarnings="true"
+    >
+        <include>
+            <directory>../../lib</directory>
+        </include>
+    </source>
+
+    <extensions>
+    </extensions>
+</phpunit>