From a0b29ecf65883449c2327fbe6e9a5a9ec114d2e7 Mon Sep 17 00:00:00 2001
From: Jonas <jonas@freesources.org>
Date: Wed, 14 Oct 2026 18:01:31 +0200
Subject: [PATCH] feat(backend): add config lexicon

Also use the new constants to load the settings in code.

Signed-off-by: Jonas <jonas@freesources.org>
Assisted-by: ClaudeCode:claude-opus-5-5
---
 lib/AppInfo/Application.php                |  3 +
 lib/ConfigLexicon.php                      | 97 ++++++++++++++++++++++
 lib/Controller/SettingsController.php      |  5 +-
 lib/Fs/UserFolderHelper.php                |  7 +-
 lib/Service/CollectiveGarbageCollector.php |  6 +-
 lib/Settings/Admin.php                     |  3 +-
 tests/Unit/ConfigLexiconTest.php           | 38 +++++++++
 7 files changed, 150 insertions(+), 9 deletions(-)
 create mode 100644 lib/ConfigLexicon.php
 create mode 100644 tests/Unit/ConfigLexiconTest.php

diff --git a/lib/AppInfo/Application.php b/lib/AppInfo/Application.php
index 3680b84bad..05a0aab2c1 100644
--- a/lib/AppInfo/Application.php
+++ b/lib/AppInfo/Application.php
@@ -12,6 +12,7 @@
 use OCA\Circles\Events\CircleDestroyedEvent;
 use OCA\Circles\Events\EditingCircleEvent;
 use OCA\Collectives\CacheListener;
+use OCA\Collectives\ConfigLexicon;
 use OCA\Collectives\Dashboard\RecentPagesWidget;
 use OCA\Collectives\Db\CollectiveMapper;
 use OCA\Collectives\Db\CollectiveVersionMapper;
@@ -86,6 +87,8 @@ public function register(IRegistrationContext $context): void {
 
 		$context->registerMiddleware(PublicOCSMiddleware::class);
 
+		$context->registerConfigLexicon(ConfigLexicon::class);
+
 		$context->registerService(MountProvider::class, fn (ContainerInterface $c) => new MountProvider(
 			$c->get(CollectiveHelper::class),
 			$c->get(CollectiveFolderManager::class),
diff --git a/lib/ConfigLexicon.php b/lib/ConfigLexicon.php
new file mode 100644
index 0000000000..b8fe4f09a2
--- /dev/null
+++ b/lib/ConfigLexicon.php
@@ -0,0 +1,97 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCA\Collectives;
+
+use OCP\Config\Lexicon\Entry;
+use OCP\Config\Lexicon\ILexicon;
+use OCP\Config\Lexicon\Strictness;
+use OCP\Config\ValueType;
+use OCP\IAppConfig;
+
+/**
+ * Config Lexicon for collectives.
+ *
+ * Please Add & Manage your Config Keys in that file and keep the Lexicon up to date!
+ *
+ * {@see ILexicon}
+ */
+class ConfigLexicon implements ILexicon {
+	public const DEFAULT_USER_FOLDER = 'default_user_folder';
+	public const ORPHANED_COLLECTIVES = 'orphaned_collectives';
+	public const MIGRATED_BACKLINKS = 'migrated_backlinks';
+	public const MIGRATED_SLUGS = 'migrated_slugs';
+	public const MIGRATED_USER_FOLDER_SETTINGS = 'migrated_user_folder_settings';
+
+	public const USER_FOLDER = 'user_folder';
+
+	#[\Override]
+	public function getStrictness(): Strictness {
+		return Strictness::IGNORE;
+	}
+
+	#[\Override]
+	public function getAppConfigs(): array {
+		return [
+			new Entry(
+				self::DEFAULT_USER_FOLDER,
+				ValueType::STRING,
+				defaultRaw: '',
+				definition: 'Default path of the collectives folder in user home directories',
+				lazy: false,
+				note: 'Empty means a localized "/Collectives" folder. Users can override it with the user config key user_folder.',
+			),
+			new Entry(
+				self::ORPHANED_COLLECTIVES,
+				ValueType::ARRAY,
+				defaultRaw: [],
+				definition: 'IDs of collectives whose team was missing during the last garbage collection run',
+				lazy: true,
+				flags: IAppConfig::FLAG_INTERNAL,
+			),
+			new Entry(
+				self::MIGRATED_BACKLINKS,
+				ValueType::BOOL,
+				defaultRaw: false,
+				definition: 'Whether the backlinks repair step has completed',
+				lazy: false,
+				flags: IAppConfig::FLAG_INTERNAL,
+			),
+			new Entry(
+				self::MIGRATED_SLUGS,
+				ValueType::BOOL,
+				defaultRaw: false,
+				definition: 'Whether the slug generation repair step has completed',
+				lazy: false,
+				flags: IAppConfig::FLAG_INTERNAL,
+			),
+			new Entry(
+				self::MIGRATED_USER_FOLDER_SETTINGS,
+				ValueType::BOOL,
+				defaultRaw: false,
+				definition: 'Whether the user folder settings repair step has completed',
+				lazy: false,
+				flags: IAppConfig::FLAG_INTERNAL,
+			),
+		];
+	}
+
+	#[\Override]
+	public function getUserConfigs(): array {
+		return [
+			new Entry(
+				self::USER_FOLDER,
+				ValueType::STRING,
+				definition: 'Path of the collectives folder in the user home directory',
+				lazy: false,
+				note: 'No lexicon default on purpose: callers fall back to the app config key default_user_folder.',
+			),
+		];
+	}
+}
diff --git a/lib/Controller/SettingsController.php b/lib/Controller/SettingsController.php
index 85e24838dc..c26e469ef0 100644
--- a/lib/Controller/SettingsController.php
+++ b/lib/Controller/SettingsController.php
@@ -9,6 +9,7 @@
 
 namespace OCA\Collectives\Controller;
 
+use OCA\Collectives\ConfigLexicon;
 use OCP\AppFramework\Http;
 use OCP\AppFramework\Http\Attribute\NoAdminRequired;
 use OCP\AppFramework\Http\DataResponse;
@@ -37,7 +38,7 @@ public function __construct(
 	 * @throws OCSBadRequestException
 	 */
 	private function validateGetUserSetting(string $setting): void {
-		if ($setting === 'user_folder') {
+		if ($setting === ConfigLexicon::USER_FOLDER) {
 			return;
 		}
 
@@ -52,7 +53,7 @@ private function validateSetUserSetting(string $setting, ?string $value): void {
 			throw new OCSBadRequestException('Empty value for setting ' . $setting);
 		}
 
-		if ($setting === 'user_folder') {
+		if ($setting === ConfigLexicon::USER_FOLDER) {
 			// No root folder, has to start with `/`, not allowed to end with `/`
 			if ($value === '/'
 				|| !(str_starts_with($value, '/'))
diff --git a/lib/Fs/UserFolderHelper.php b/lib/Fs/UserFolderHelper.php
index 50abf39015..1aae882350 100644
--- a/lib/Fs/UserFolderHelper.php
+++ b/lib/Fs/UserFolderHelper.php
@@ -10,6 +10,7 @@
 namespace OCA\Collectives\Fs;
 
 use OC_Util;
+use OCA\Collectives\ConfigLexicon;
 use OCP\Config\IUserConfig;
 use OCP\Files\Folder;
 use OCP\Files\IRootFolder;
@@ -29,15 +30,15 @@ public function __construct(
 	}
 
 	public function getUserFolderSetting(string $userId): string {
-		$defaultUserFolder = $this->appConfig->getValueString('collectives', 'default_user_folder', '');
+		$defaultUserFolder = $this->appConfig->getValueString('collectives', ConfigLexicon::DEFAULT_USER_FOLDER, '');
 		// Get collectives user folder from settings and default to translated 'Collectives'
-		$userCollectivesPath = $this->userConfig->getValueString($userId, 'collectives', 'user_folder', $defaultUserFolder);
+		$userCollectivesPath = $this->userConfig->getValueString($userId, 'collectives', ConfigLexicon::USER_FOLDER, $defaultUserFolder);
 		if ($userCollectivesPath === '') {
 			$user = $this->userManager->get($userId);
 			$userLang = $this->l10nFactory->getUserLanguage($user);
 			$l10n = $this->l10nFactory->get('collectives', $userLang);
 			$userCollectivesPath = DIRECTORY_SEPARATOR . '.' . $l10n->t('Collectives');
-			$this->userConfig->setValueString($userId, 'collectives', 'user_folder', $userCollectivesPath);
+			$this->userConfig->setValueString($userId, 'collectives', ConfigLexicon::USER_FOLDER, $userCollectivesPath);
 		}
 
 		return $userCollectivesPath;
diff --git a/lib/Service/CollectiveGarbageCollector.php b/lib/Service/CollectiveGarbageCollector.php
index 88f1ad744e..c9b6fc64ba 100644
--- a/lib/Service/CollectiveGarbageCollector.php
+++ b/lib/Service/CollectiveGarbageCollector.php
@@ -9,6 +9,7 @@
 
 namespace OCA\Collectives\Service;
 
+use OCA\Collectives\ConfigLexicon;
 use OCA\Collectives\Db\Collective;
 use OCA\Collectives\Db\CollectiveMapper;
 use OCP\AppFramework\Utility\ITimeFactory;
@@ -16,7 +17,6 @@
 use Psr\Log\LoggerInterface;
 
 class CollectiveGarbageCollector {
-	private const CONFIG_KEY = 'orphaned_collectives';
 	// Collectives need to be orphaned for at least a week before they get purged
 	public const GRACE_PERIOD = 60 * 60 * 24 * 7;
 
@@ -58,7 +58,7 @@ public function purgeOrphanedCollectives(): int {
 		}
 
 		/** @var array<string, int> $previouslyOrphaned */
-		$previouslyOrphaned = $this->appConfig->getValueArray('collectives', self::CONFIG_KEY, lazy: true);
+		$previouslyOrphaned = $this->appConfig->getValueArray('collectives', ConfigLexicon::ORPHANED_COLLECTIVES, lazy: true);
 		$now = $this->timeFactory->getTime();
 		$stillOrphaned = [];
 		$purgeCount = 0;
@@ -85,7 +85,7 @@ public function purgeOrphanedCollectives(): int {
 		}
 
 		// Only keep collectives that were orphaned in this run
-		$this->appConfig->setValueArray('collectives', self::CONFIG_KEY, $stillOrphaned, lazy: true);
+		$this->appConfig->setValueArray('collectives', ConfigLexicon::ORPHANED_COLLECTIVES, $stillOrphaned, lazy: true);
 
 		return $purgeCount;
 	}
diff --git a/lib/Settings/Admin.php b/lib/Settings/Admin.php
index 0344b496d8..c50a53d483 100644
--- a/lib/Settings/Admin.php
+++ b/lib/Settings/Admin.php
@@ -10,6 +10,7 @@
 namespace OCA\Collectives\Settings;
 
 use OCA\Collectives\AppInfo\Application;
+use OCA\Collectives\ConfigLexicon;
 use OCP\AppFramework\Http\TemplateResponse;
 use OCP\AppFramework\Services\IInitialState;
 use OCP\IAppConfig;
@@ -25,7 +26,7 @@ public function __construct(
 
 	public function getForm(): TemplateResponse {
 		$parameters = [
-			'default_user_folder' => $this->appConfig->getValueString('collectives', 'default_user_folder', ''),
+			'default_user_folder' => $this->appConfig->getValueString('collectives', ConfigLexicon::DEFAULT_USER_FOLDER, ''),
 		];
 		$this->initialState->provideInitialState('adminSettings', $parameters);
 
diff --git a/tests/Unit/ConfigLexiconTest.php b/tests/Unit/ConfigLexiconTest.php
new file mode 100644
index 0000000000..f8663a721e
--- /dev/null
+++ b/tests/Unit/ConfigLexiconTest.php
@@ -0,0 +1,38 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace Unit;
+
+use OCA\Collectives\ConfigLexicon;
+use OCP\Config\Lexicon\Entry;
+use OCP\Config\Lexicon\Preset;
+use Test\TestCase;
+
+class ConfigLexiconTest extends TestCase {
+	private ConfigLexicon $lexicon;
+
+	protected function setUp(): void {
+		parent::setUp();
+		$this->lexicon = new ConfigLexicon();
+	}
+
+	public function testAppConfigKeysAreUnique(): void {
+		$keys = array_map(static fn (Entry $e) => $e->getKey(), $this->lexicon->getAppConfigs());
+		self::assertSame(array_unique($keys), $keys);
+	}
+
+	public function testUserFolderHasNoLexiconDefault(): void {
+		$entries = array_filter(
+			$this->lexicon->getUserConfigs(),
+			static fn (Entry $e) => $e->getKey() === ConfigLexicon::USER_FOLDER,
+		);
+		self::assertCount(1, $entries);
+		self::assertNull(array_values($entries)[0]->getDefault(Preset::NONE));
+	}
+}