feat: add versioned import contract foundation

.github/workflows/openapi.yml

@@ -78,6 +78,10 @@ jobs:
       - name: Regenerate OpenAPI
         run: composer run openapi
 
+      - name: Regenerate TypeScript OpenAPI types
+        if: steps.check_typescript_openapi.outputs.files_exists == 'true'
+        run: npm run typescript:generate
+
       - name: Check openapi*.json and typescript changes
         run: |
           bash -c "[[ ! \"`git status --porcelain `\" ]] || (echo 'Please run \"composer run openapi\" and commit the openapi*.json files and, if applicable, src/types/openapi/openapi*.ts. See the diff below.' && exit 1)"

REUSE.toml

@@ -27,6 +27,7 @@ path = [
   "package-lock.json",
   "package.json",
   "psalm.xml",
+  "src/types/openapi/*.ts",
   "tests/integration/composer.json",
   "tests/integration/composer.lock",
   "tests/integration/features/**/*.feature",

appinfo/info.xml

@@ -49,6 +49,7 @@ Developed with ❤️ by [LibreCode](https://librecode.coop). Help us transform
 	</repair-steps>
 	<commands>
 		<command>OCA\ProfileFields\Command\Data\Export</command>
+		<command>OCA\ProfileFields\Command\Data\Import</command>
 		<command>OCA\ProfileFields\Command\Data\Clear</command>
 		<command>OCA\ProfileFields\Command\Developer\Reset</command>
 	</commands>

lib/AppInfo/Application.php

@@ -38,18 +38,35 @@ public function register(IRegistrationContext $context): void {
 
 	#[\Override]
 	public function boot(IBootContext $context): void {
-		$request = $context->getServerContainer()->get(IRequest::class);
-		$path = $request->getPathInfo();
-		$requestUri = $request->getRequestUri();
+		try {
+			$context->injectFn($this->bootWithRequest(...));
+		} catch (\Throwable) {
+			return;
+		}
+	}
+
+	private function bootWithRequest(IRequest $request): void {
+		$path = $this->readRequestString(static fn (): string|false => $request->getPathInfo());
+		$requestUri = $this->readRequestString(static fn (): string => $request->getRequestUri());
 
 		if (
-			($path !== false && str_contains($path, '/settings/users'))
-			|| str_contains($requestUri, '/settings/users')
+			($path !== null && str_contains($path, '/settings/users'))
+			|| ($requestUri !== null && str_contains($requestUri, '/settings/users'))
 		) {
 			self::loadUserManagementAssets();
 		}
 	}
 
+	private function readRequestString(callable $reader): ?string {
+		try {
+			$value = $reader();
+		} catch (\Throwable) {
+			return null;
+		}
+
+		return is_string($value) && $value !== '' ? $value : null;
+	}
+
 	public static function loadUserManagementAssets(): void {
 		if (self::$userManagementAssetsLoaded) {
 			return;

lib/Command/Data/Export.php

@@ -19,6 +19,8 @@
 use Symfony\Component\Console\Output\OutputInterface;
 
 class Export extends Command {
+	private const SCHEMA_VERSION = 1;
+
 	public function __construct(
 		private FieldDefinitionService $fieldDefinitionService,
 		private FieldValueMapper $fieldValueMapper,
@@ -47,17 +49,30 @@ protected function configure(): void {
 
 	#[\Override]
 	protected function execute(InputInterface $input, OutputInterface $output): int {
-		$payload = [
-			'exported_at' => gmdate(DATE_ATOM),
-			'definitions' => array_map(
-				static fn ($definition): array => $definition->jsonSerialize(),
-				$this->fieldDefinitionService->findAllOrdered(),
-			),
-			'values' => array_map(
-				fn (FieldValue $value): array => $this->serializeValue($value),
-				$this->fieldValueMapper->findAllOrdered(),
-			),
-		];
+		try {
+			$definitions = $this->fieldDefinitionService->findAllOrdered();
+			$fieldKeysByDefinitionId = [];
+			foreach ($definitions as $definition) {
+				$fieldKeysByDefinitionId[$definition->getId()] = $definition->getFieldKey();
+			}
+
+			$payload = [
+				'schema_version' => self::SCHEMA_VERSION,
+				'exported_at' => gmdate(DATE_ATOM),
+				'definitions' => array_map(
+					static fn ($definition): array => $definition->jsonSerialize(),
+					$definitions,
+				),
+				'values' => array_map(
+					fn (FieldValue $value): array => $this->serializeValue($value, $fieldKeysByDefinitionId),
+					$this->fieldValueMapper->findAllOrdered(),
+				),
+			];
+		} catch (\Throwable $exception) {
+			$output->writeln('<error>Failed to build export payload.</error>');
+			$output->writeln(sprintf('<error>%s</error>', $exception->getMessage()));
+			return self::FAILURE;
+		}
 
 		try {
 			$json = json_encode(
@@ -88,16 +103,22 @@ protected function execute(InputInterface $input, OutputInterface $output): int
 	/**
 	 * @return array<string, mixed>
 	 */
-	private function serializeValue(FieldValue $value): array {
+	private function serializeValue(FieldValue $value, array $fieldKeysByDefinitionId): array {
 		try {
 			$decodedValue = json_decode($value->getValueJson(), true, 512, JSON_THROW_ON_ERROR);
 		} catch (JsonException $exception) {
 			throw new \RuntimeException('Failed to decode stored field value JSON.', 0, $exception);
 		}
 
+		$fieldKey = $fieldKeysByDefinitionId[$value->getFieldDefinitionId()] ?? null;
+		if (!is_string($fieldKey) || $fieldKey === '') {
+			throw new \RuntimeException(sprintf('Could not resolve field_key for field definition %d.', $value->getFieldDefinitionId()));
+		}
+
 		return [
 			'id' => $value->getId(),
 			'field_definition_id' => $value->getFieldDefinitionId(),
+			'field_key' => $fieldKey,
 			'user_uid' => $value->getUserUid(),
 			'value' => $decodedValue,
 			'current_visibility' => $value->getCurrentVisibility(),

lib/Command/Data/Import.php

@@ -0,0 +1,98 @@
+<?php
+
+/**
+ * SPDX-FileCopyrightText: 2026 LibreCode coop and LibreCode contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+declare(strict_types=1);
+
+namespace OCA\ProfileFields\Command\Data;
+
+use JsonException;
+use OCA\ProfileFields\Service\DataImportService;
+use Symfony\Component\Console\Command\Command;
+use Symfony\Component\Console\Input\InputInterface;
+use Symfony\Component\Console\Input\InputOption;
+use Symfony\Component\Console\Output\OutputInterface;
+
+class Import extends Command {
+	public function __construct(
+		private DataImportService $dataImportService,
+	) {
+		parent::__construct();
+	}
+
+	#[\Override]
+	protected function configure(): void {
+		$this
+			->setName('profile_fields:data:import')
+			->setDescription('Import persisted Profile Fields definitions and values from a JSON payload')
+			->addOption(
+				name: 'input',
+				shortcut: 'i',
+				mode: InputOption::VALUE_REQUIRED,
+				description: 'Read the JSON import payload from a file',
+			)
+			->addOption(
+				name: 'dry-run',
+				shortcut: null,
+				mode: InputOption::VALUE_NONE,
+				description: 'Validate the payload and report the import summary without persisting data',
+			);
+	}
+
+	#[\Override]
+	protected function execute(InputInterface $input, OutputInterface $output): int {
+		$sourcePath = $input->getOption('input');
+		if (!is_string($sourcePath) || $sourcePath === '') {
+			$output->writeln('<error>Please provide --input with a JSON file path.</error>');
+			return self::FAILURE;
+		}
+
+		$rawPayload = @file_get_contents($sourcePath);
+		if ($rawPayload === false) {
+			$output->writeln(sprintf('<error>Could not read import payload from %s.</error>', $sourcePath));
+			return self::FAILURE;
+		}
+
+		try {
+			$decodedPayload = json_decode($rawPayload, true, 512, JSON_THROW_ON_ERROR);
+		} catch (JsonException $exception) {
+			$output->writeln('<error>Failed to decode import payload JSON.</error>');
+			$output->writeln(sprintf('<error>%s</error>', $exception->getMessage()));
+			return self::FAILURE;
+		}
+
+		if (!is_array($decodedPayload)) {
+			$output->writeln('<error>Import payload must decode to a JSON object.</error>');
+			return self::FAILURE;
+		}
+
+		try {
+			$summary = $this->dataImportService->import($decodedPayload, (bool)$input->getOption('dry-run'));
+		} catch (\Throwable $throwable) {
+			$output->writeln('<error>Import validation failed.</error>');
+			$output->writeln(sprintf('<error>%s</error>', $throwable->getMessage()));
+			return self::FAILURE;
+		}
+
+		$output->writeln((bool)$input->getOption('dry-run')
+			? '<info>Profile Fields data import dry-run completed.</info>'
+			: '<info>Profile Fields data imported.</info>');
+		$output->writeln(sprintf(
+			'<info>Definitions: %d created, %d updated, %d skipped.</info>',
+			$summary['created_definitions'],
+			$summary['updated_definitions'],
+			$summary['skipped_definitions'],
+		));
+		$output->writeln(sprintf(
+			'<info>Values: %d created, %d updated, %d skipped.</info>',
+			$summary['created_values'],
+			$summary['updated_values'],
+			$summary['skipped_values'],
+		));
+
+		return self::SUCCESS;
+	}
+}

lib/Listener/BeforeTemplateRenderedListener.php

@@ -16,7 +16,7 @@
 /**
  * @template-implements IEventListener<Event>
  */
-readonly class BeforeTemplateRenderedListener implements IEventListener {
+class BeforeTemplateRenderedListener implements IEventListener {
 	#[\Override]
 	public function handle(Event $event): void {
 		if ($event::class !== '\\OCA\\Settings\\Events\\BeforeTemplateRenderedEvent') {

lib/ResponseDefinitions.php

@@ -46,6 +46,8 @@
  *     user_uid: string,
  *     value: ProfileFieldsValuePayload,
  *     current_visibility: ProfileFieldsVisibility,
+ *     updated_by_uid: string,
+ *     updated_at: string,
  * }
  * @psalm-type ProfileFieldsEditableField = array{
  *     definition: ProfileFieldsDefinition,