feat: external plugin system

.github/workflows/plugin_host_ci.yml

@@ -0,0 +1,137 @@
+name: Plugin host & SDK - build and test
+
+permissions:
+  contents: read
+
+on:
+  push:
+    paths:
+      - "plugin-host/**"
+      - ".github/workflows/plugin_host_ci.yml"
+  pull_request:
+    paths:
+      - "plugin-host/**"
+      - ".github/workflows/plugin_host_ci.yml"
+  workflow_dispatch:
+
+jobs:
+  unit:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      # Node 22 matches the host runtime requirement (Extism runInWorker needs Node >= 22, plan §7).
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: |
+            plugin-host/plugin-sdk/package-lock.json
+            plugin-host/app/package-lock.json
+
+      # The SDK is a file: dependency of the app and must be built first so the app's `tsc` can
+      # resolve @valtimo/plugin-sdk types.
+      - name: SDK - install
+        working-directory: plugin-host/plugin-sdk
+        run: npm ci
+
+      - name: SDK - build (tsc)
+        working-directory: plugin-host/plugin-sdk
+        run: npm run build
+
+      - name: SDK - test
+        working-directory: plugin-host/plugin-sdk
+        run: npm run test:cov
+
+      - name: App - install
+        working-directory: plugin-host/app
+        run: npm ci
+
+      - name: App - build (tsc)
+        working-directory: plugin-host/app
+        run: npm run build
+
+      - name: App - test
+        working-directory: plugin-host/app
+        run: npm run test:cov
+
+  # L3 (Wasm/Extism) tests: compile the fixture plugin with the real SDK toolchain and run it under
+  # Extism. Kept separate from `unit` because it needs the extism-js compiler, which is not committed
+  # (plugin-host/.bin is gitignored) and is downloaded here.
+  wasm:
+    runs-on: ubuntu-latest
+    env:
+      # Pin the Extism JS PDK compiler version. Bump together with @extism/js-pdk in the fixture.
+      EXTISM_JS_VERSION: "1.5.1"
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: |
+            plugin-host/plugin-sdk/package-lock.json
+            plugin-host/app/package-lock.json
+            plugin-host/test-fixtures/test-plugin/package-lock.json
+
+      - name: Download extism-js compiler
+        run: |
+          mkdir -p plugin-host/.bin
+          url="https://github.com/extism/js-pdk/releases/download/v${EXTISM_JS_VERSION}/extism-js-x86_64-linux-v${EXTISM_JS_VERSION}.gz"
+          curl -sSfL "$url" -o /tmp/extism-js.gz
+          gunzip -c /tmp/extism-js.gz > plugin-host/.bin/extism-js
+          chmod +x plugin-host/.bin/extism-js
+          plugin-host/.bin/extism-js --version
+
+      # The fixture bundles @valtimo/plugin-sdk from its built dist, so the SDK must be built first.
+      - name: SDK - install & build
+        working-directory: plugin-host/plugin-sdk
+        run: npm ci && npm run build
+
+      - name: Fixture - install deps
+        working-directory: plugin-host/test-fixtures/test-plugin
+        run: npm install
+
+      - name: App - install
+        working-directory: plugin-host/app
+        run: npm ci
+
+      # globalSetup compiles the fixture to Wasm (finds extism-js on PATH via plugin-host/.bin).
+      - name: App - Wasm/Extism tests (L3)
+        working-directory: plugin-host/app
+        run: npm run test:wasm
+
+  # L4 (integration) tests: real Postgres + RabbitMQ via Testcontainers. The ubuntu runner ships a
+  # working Docker daemon, which Testcontainers uses directly.
+  integration:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: |
+            plugin-host/plugin-sdk/package-lock.json
+            plugin-host/app/package-lock.json
+
+      # The app's tsc/type surface pulls @valtimo/plugin-sdk, so build the SDK first.
+      - name: SDK - install & build
+        working-directory: plugin-host/plugin-sdk
+        run: npm ci && npm run build
+
+      - name: App - install
+        working-directory: plugin-host/app
+        run: npm ci
+
+      - name: App - integration tests (Testcontainers)
+        working-directory: plugin-host/app
+        run: npm run test:int

backend/admin-settings/src/main/kotlin/com/ritense/adminsettings/autoconfigure/AdminSettingsAutoConfiguration.kt

@@ -23,13 +23,16 @@ import com.ritense.adminsettings.importer.AdminSettingsLogoImporter
 import com.ritense.adminsettings.repository.AccentColorsRepository
 import com.ritense.adminsettings.repository.AdminSettingsLogoRepository
 import com.ritense.adminsettings.repository.FeatureToggleOverridesRepository
+import com.ritense.adminsettings.repository.MenuConfigurationRepository
 import com.ritense.adminsettings.security.config.AdminSettingsHttpSecurityConfigurer
 import com.ritense.adminsettings.service.AccentColorsService
 import com.ritense.adminsettings.service.AdminSettingsLogoService
 import com.ritense.adminsettings.service.FeatureToggleOverridesService
+import com.ritense.adminsettings.service.MenuConfigurationService
 import com.ritense.adminsettings.web.rest.AccentColorsResource
 import com.ritense.adminsettings.web.rest.AdminSettingsLogoResource
 import com.ritense.adminsettings.web.rest.FeatureToggleOverridesResource
+import com.ritense.adminsettings.web.rest.MenuConfigurationResource
 import com.ritense.authorization.AuthorizationService
 import org.springframework.boot.autoconfigure.AutoConfiguration
 import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean
@@ -39,7 +42,7 @@ import org.springframework.core.annotation.Order
 import org.springframework.data.jpa.repository.config.EnableJpaRepositories
 
 @AutoConfiguration
-@EnableJpaRepositories(basePackageClasses = [AdminSettingsLogoRepository::class, FeatureToggleOverridesRepository::class, AccentColorsRepository::class])
+@EnableJpaRepositories(basePackageClasses = [AdminSettingsLogoRepository::class, FeatureToggleOverridesRepository::class, AccentColorsRepository::class, MenuConfigurationRepository::class])
 @EntityScan(basePackages = ["com.ritense.adminsettings.domain"])
 class AdminSettingsAutoConfiguration {
 
@@ -110,6 +113,26 @@ class AdminSettingsAutoConfiguration {
         return AccentColorsResource(accentColorsService)
     }
 
+    @Bean
+    @ConditionalOnMissingBean(MenuConfigurationService::class)
+    fun menuConfigurationService(
+        menuConfigurationRepository: MenuConfigurationRepository,
+        objectMapper: ObjectMapper,
+    ): MenuConfigurationService {
+        return MenuConfigurationService(
+            menuConfigurationRepository,
+            objectMapper,
+        )
+    }
+
+    @Bean
+    @ConditionalOnMissingBean(MenuConfigurationResource::class)
+    fun menuConfigurationResource(
+        menuConfigurationService: MenuConfigurationService
+    ): MenuConfigurationResource {
+        return MenuConfigurationResource(menuConfigurationService)
+    }
+
     @Bean
     @ConditionalOnMissingBean(AdminSettingsFeatureToggleImporter::class)
     fun adminSettingsFeatureToggleImporter(

backend/admin-settings/src/main/kotlin/com/ritense/adminsettings/domain/MenuConfiguration.kt

@@ -0,0 +1,44 @@
+/*
+ * Copyright 2015-2026 Ritense BV, the Netherlands.
+ *
+ * Licensed under EUPL, Version 1.2 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" basis,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.ritense.adminsettings.domain
+
+import jakarta.persistence.Column
+import jakarta.persistence.Entity
+import jakarta.persistence.Id
+import jakarta.persistence.Table
+
+/**
+ * Singleton row holding the application's left-hand menu structure as opaque, frontend-owned JSON
+ * (exactly like [AccentColors] holds colours). The backend never interprets the structure; the
+ * frontend resolves it against its catalog registry at startup.
+ */
+@Entity
+@Table(name = "admin_settings_menu_configuration")
+open class MenuConfiguration(
+
+    @Id
+    @Column(name = "id", nullable = false)
+    open val id: String = SINGLETON_ID,
+
+    @Column(name = "configuration", columnDefinition = "TEXT", nullable = false)
+    open var configuration: String = "{}"
+) {
+
+    companion object {
+        const val SINGLETON_ID = "singleton"
+    }
+}

backend/admin-settings/src/main/kotlin/com/ritense/adminsettings/repository/MenuConfigurationRepository.kt

@@ -0,0 +1,22 @@
+/*
+ * Copyright 2015-2026 Ritense BV, the Netherlands.
+ *
+ * Licensed under EUPL, Version 1.2 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" basis,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.ritense.adminsettings.repository
+
+import com.ritense.adminsettings.domain.MenuConfiguration
+import org.springframework.data.jpa.repository.JpaRepository
+
+interface MenuConfigurationRepository : JpaRepository<MenuConfiguration, String>

backend/admin-settings/src/main/kotlin/com/ritense/adminsettings/security/config/AdminSettingsHttpSecurityConfigurer.kt

@@ -50,6 +50,10 @@ class AdminSettingsHttpSecurityConfigurer : HttpSecurityConfigurer {
                     .authenticated()
                     .requestMatchers(antMatcher(PUT, "/api/management/v1/admin-settings/accent-colors"))
                     .hasAuthority(ADMIN)
+                    .requestMatchers(antMatcher(GET, "/api/v1/admin-settings/menu-configuration"))
+                    .authenticated()
+                    .requestMatchers(antMatcher(PUT, "/api/management/v1/admin-settings/menu-configuration"))
+                    .hasAuthority(ADMIN)
             }
         } catch (e: Exception) {
             throw HttpConfigurerConfigurationException(e)

backend/admin-settings/src/main/kotlin/com/ritense/adminsettings/service/MenuConfigurationService.kt

@@ -0,0 +1,68 @@
+/*
+ * Copyright 2015-2026 Ritense BV, the Netherlands.
+ *
+ * Licensed under EUPL, Version 1.2 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" basis,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.ritense.adminsettings.service
+
+import com.fasterxml.jackson.databind.JsonNode
+import com.fasterxml.jackson.databind.ObjectMapper
+import com.ritense.adminsettings.domain.MenuConfiguration
+import com.ritense.adminsettings.domain.MenuConfiguration.Companion.SINGLETON_ID
+import com.ritense.adminsettings.repository.MenuConfigurationRepository
+import com.ritense.adminsettings.web.rest.dto.MenuConfigurationDto
+import org.springframework.data.repository.findByIdOrNull
+import org.springframework.http.HttpStatus
+import org.springframework.transaction.annotation.Transactional
+import org.springframework.web.server.ResponseStatusException
+
+open class MenuConfigurationService(
+    private val menuConfigurationRepository: MenuConfigurationRepository,
+    private val objectMapper: ObjectMapper,
+) {
+
+    @Transactional(readOnly = true)
+    open fun getMenuConfiguration(): MenuConfigurationDto {
+        val entity = menuConfigurationRepository.findByIdOrNull(SINGLETON_ID)
+        val configuration: JsonNode = if (entity != null) {
+            objectMapper.readTree(entity.configuration)
+        } else {
+            objectMapper.createObjectNode()
+        }
+        return MenuConfigurationDto(configuration)
+    }
+
+    @Transactional
+    open fun updateMenuConfiguration(configuration: JsonNode): MenuConfigurationDto {
+        val serializedConfiguration = objectMapper.writeValueAsString(configuration)
+        if (serializedConfiguration.length > MAX_CONFIGURATION_LENGTH) {
+            throw ResponseStatusException(
+                HttpStatus.BAD_REQUEST,
+                "Menu configuration exceeds the maximum size of $MAX_CONFIGURATION_LENGTH characters"
+            )
+        }
+
+        val entity = menuConfigurationRepository.findByIdOrNull(SINGLETON_ID)
+            ?: MenuConfiguration()
+
+        entity.configuration = serializedConfiguration
+        menuConfigurationRepository.save(entity)
+
+        return MenuConfigurationDto(configuration)
+    }
+
+    companion object {
+        const val MAX_CONFIGURATION_LENGTH = 100_000
+    }
+}

backend/admin-settings/src/main/kotlin/com/ritense/adminsettings/web/rest/AccentColorsResource.kt

@@ -20,6 +20,7 @@ import com.ritense.adminsettings.service.AccentColorsService
 import com.ritense.adminsettings.web.rest.dto.AccentColorsDto
 import com.ritense.valtimo.contract.annotation.SkipComponentScan
 import com.ritense.valtimo.contract.domain.ValtimoMediaType.APPLICATION_JSON_UTF8_VALUE
+import com.ritense.valtimo.contract.endpoint.EndpointDescription
 import jakarta.validation.Valid
 import org.springframework.http.ResponseEntity
 import org.springframework.web.bind.annotation.GetMapping
@@ -35,11 +36,19 @@ class AccentColorsResource(
     private val accentColorsService: AccentColorsService
 ) {
 
+    @EndpointDescription(
+        en = "Get accent colors",
+        nl = "Accentkleuren ophalen",
+    )
     @GetMapping("/v1/admin-settings/accent-colors")
     fun getColors(): ResponseEntity<AccentColorsDto> {
         return ResponseEntity.ok(accentColorsService.getColors())
     }
 
+    @EndpointDescription(
+        en = "Update accent colors",
+        nl = "Accentkleuren bijwerken",
+    )
     @PutMapping("/management/v1/admin-settings/accent-colors")
     fun updateColors(
         @Valid @RequestBody dto: AccentColorsDto