feat(setup): ask which example data to load, as cards, instead of a bare Run button (#543)

The demo-data step was a Run button under a paragraph. The paragraph said the
data was safe to load and safe to delete. Neither said what was about to land
in the operator's register, and there was no way to say no.

## Declining was unsayable, and that reopened the wizard for ever

This app implements a `skip-demo-data` action. No manifest step could reach it:
the only step was the run-action that INSTALLS. So an operator who did not want
example data had no way to record that, `demo-data` stayed `done: false`, and
CnAppRoot reopens the wizard while any optional step is outstanding. On every
fresh browser profile, over every page, until they imported data they did not
want.

Measured across the fleet on 2026-09-05: fifteen apps implement that action and
not one declares a step that can post it.

## What the step asks now

Two cards, read from the server: "None, I will set this up myself" and the
dataset this app ships, with its object count. Picking one is an answer, and
`none` closes both steps without importing anything.

The list comes from `GET /api/setup/status` as `datasets` — the step declares
`optionsSource` and carries no options of its own, so nothing in the manifest
can disagree with what will actually be imported. The count is read from the
descriptor file, so the card promises the number that lands.

The card's description carries NO number, deliberately: the wizard translates a
description by literal lookup, so an interpolated count would leave a Dutch
operator reading English. The count travels as `objectCount` and the card
renders it as a stat with a label the library translates.

## Compatibility

`install-demo-data` still works and still means "the dataset this app ships",
so a runbook or script that posts it keeps working. `skip-demo-data` now writes
both keys rather than only the decision flag.

## Verification

21 PHPUnit tests pass, 9 of them new. PHPCS clean, ESLint clean, prettier
clean. All 75 applicable hydra gates green.

Requires @conduction/nextcloud-vue with CnChoiceCards and hydra-gates >=
v1.15.0 for manifest schema 2.33.0.

Co-authored-by: Conduction Release Bot <release-bot@conduction.nl>
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: 3 people

appinfo/routes.php

@@ -14,6 +14,7 @@
 		// First-time setup wizard (ADR-042) — the standard CnSetupWizard contract.
 		['name' => 'setup#status',    'url' => '/api/setup/status',            'verb' => 'GET'],
 		['name' => 'setup#runAction', 'url' => '/api/setup/action/{actionId}', 'verb' => 'POST', 'requirements' => ['actionId' => '[a-z0-9\\-]+']],
+		['name' => 'setup#saveConfig', 'url' => '/api/setup/config',           'verb' => 'POST'],
 		['name' => 'manifest#index', 'url' => '/api/manifest', 'verb' => 'GET'],
 
 		// Metrics and health

composer.lock

@@ -1150,7 +1150,15 @@ OC.L10N.register(
     "Version": "Versie",
     "How many dashboards there are, and who they belong to.": "Hoeveel dashboards er zijn, en van wie ze zijn.",
     "Store": "Store",
-    "Install dashboard configurations that other organisations have published: a set of tiles, a layout, or the flows behind them.": "Installeer registers, schema's en flows die andere organisaties hebben gepubliceerd."
+    "Install dashboard configurations that other organisations have published: a set of tiles, a layout, or the flows behind them.": "Installeer registers, schema's en flows die andere organisaties hebben gepubliceerd.",
+    "Load example data?": "Voorbeeldgegevens laden?",
+    "Example data fills the lists, detail pages and dashboards so you can see the app working straight away. Pick \"None\" on a production install.": "Voorbeeldgegevens vullen de lijsten, detailpagina’s en dashboards, zodat je de app meteen ziet werken. Kies \"Geen\" op een productieomgeving.",
+    "Load the example data": "Laad de voorbeeldgegevens",
+    "Loads what you picked. The data is obviously sample data, it is safe to run more than once, and you can delete it afterwards.": "Laadt wat je koos. De gegevens zijn herkenbaar voorbeeldgegevens, je kunt dit meer dan een keer uitvoeren en je kunt ze daarna verwijderen.",
+    "None, I will set this up myself": "Geen, ik richt dit zelf in",
+    "Nothing is imported. You start with an empty app and add your own data.": "Er wordt niets geïmporteerd. Je begint met een lege app en voegt zelf gegevens toe.",
+    "Example data": "Voorbeeldgegevens",
+    "Sample values for every schema this app supplies, generated from the schemas themselves. It shows the lists, detail pages and dashboards working rather than telling a story. Safe to run more than once, and you can delete it afterwards.": "Voorbeeldwaarden voor elk schema dat deze app levert, gegenereerd uit de schema’s zelf. Het laat de lijsten, detailpagina’s en dashboards werkend zien in plaats van een verhaal te vertellen. Veilig om vaker uit te voeren, en je kunt het daarna verwijderen."
 },
 "nplurals=2; plural=(n != 1);"
 );

l10n/nl.js

@@ -1,5 +1,13 @@
 {
     "translations": {
+        "Load example data?": "Voorbeeldgegevens laden?",
+        "Example data fills the lists, detail pages and dashboards so you can see the app working straight away. Pick \"None\" on a production install.": "Voorbeeldgegevens vullen de lijsten, detailpagina’s en dashboards, zodat je de app meteen ziet werken. Kies \"Geen\" op een productieomgeving.",
+        "Load the example data": "Laad de voorbeeldgegevens",
+        "Loads what you picked. The data is obviously sample data, it is safe to run more than once, and you can delete it afterwards.": "Laadt wat je koos. De gegevens zijn herkenbaar voorbeeldgegevens, je kunt dit meer dan een keer uitvoeren en je kunt ze daarna verwijderen.",
+        "None, I will set this up myself": "Geen, ik richt dit zelf in",
+        "Nothing is imported. You start with an empty app and add your own data.": "Er wordt niets geïmporteerd. Je begint met een lege app en voegt zelf gegevens toe.",
+        "Example data": "Voorbeeldgegevens",
+        "Sample values for every schema this app supplies, generated from the schemas themselves. It shows the lists, detail pages and dashboards working rather than telling a story. Safe to run more than once, and you can delete it afterwards.": "Voorbeeldwaarden voor elk schema dat deze app levert, gegenereerd uit de schema’s zelf. Het laat de lijsten, detailpagina’s en dashboards werkend zien in plaats van een verhaal te vertellen. Veilig om vaker uit te voeren, en je kunt het daarna verwijderen.",
         "A short setup to get this app ready. Nothing here is required; you can close it and come back later.": "Een korte installatie om deze app klaar te zetten. Niets hiervan is verplicht; je kunt dit sluiten en later terugkomen.",
         "Demo data (optional)": "Demovoorbeelddata (optioneel)",
         "Load a small example dataset so the lists, detail pages and dashboards show a working product straight away. The data is obviously sample data, it is safe to run more than once, and it can be removed afterwards. Skip this on a production install.": "Laad een kleine voorbeeldset zodat de lijsten, detailpagina's en dashboards meteen een werkend product laten zien. De data is duidelijk voorbeelddata, veilig om meerdere keren uit te voeren en achteraf te verwijderen. Sla dit over op een productie-installatie.",

l10n/nl.json

@@ -65,6 +65,19 @@ class SetupController extends Controller {
 	 */
 	private const DEMO_DECIDED_KEY = 'demo_data_decided';
 
+	/**
+	 * App-config key holding the dataset the operator picked.
+	 *
+	 * The wizard's `choice` step writes it through `POST /api/setup/config`, and
+	 * the `run-action` step that follows reads it back. Two steps rather than
+	 * one because `CnSetupWizard::runAction()` posts to
+	 * `/api/setup/action/{action}` with no body: an action cannot carry the
+	 * answer, so the answer has to be stored before the action runs.
+	 *
+	 * @var string
+	 */
+	private const DATASET_KEY = 'demo_dataset';
+
 	/**
 	 * Constructor.
 	 *
@@ -99,19 +112,77 @@ public function __construct(
 	#[AuthorizedAdminSetting(LaunchPadAdmin::class)]
 	public function status(): JSONResponse {
 		$demoDecided = $this->appConfig->getValueString(Application::APP_ID, self::DEMO_DECIDED_KEY, '') !== '';
+		$picked      = $this->appConfig->getValueString(Application::APP_ID, self::DATASET_KEY, '');
 
 		return new JSONResponse(
 			data: [
 				'version'   => self::SETUP_VERSION,
 				'completed' => true,
+				// The choice step reads its options from here: it declares
+				// `optionsSource: datasets` and no options of its own, so a
+				// dataset missing from this list is a dataset nobody can pick.
+				'datasets'  => $this->demoDataService->listChoices(),
 				'steps'     => [
-					'demo-data' => ['done' => $demoDecided],
+					'demo-data' => ['done' => ($picked !== '')],
+					// "None" is an ANSWER, so the load step is finished the moment
+					// it is chosen: there is nothing left for the operator to run.
+					'load-demo-data' => [
+						'done' => ($demoDecided === true || $picked === DemoDataService::NONE_DATASET),
+					],
 				],
 			]
 		);
 
 	}//end status()
 
+	/**
+	 * Persist the wizard's `choice` answer.
+	 *
+	 * @return JSONResponse `{ success, config }`.
+	 *
+	 * @spec exclude Setup config write; ADR-042 contract, no per-app behavioural spec.
+	 */
+	#[AuthorizedAdminSetting(LaunchPadAdmin::class)]
+	public function saveConfig(): JSONResponse {
+		// 🔴 ONE NAMED KEY, NEVER A CALLER-SUPPLIED ONE. The body arrives from
+		// the browser and this app's own settings share the appconfig namespace,
+		// so looping over the posted keys would let this endpoint write any of
+		// them. The key is written in the source; only its value comes from the
+		// request.
+		$value = $this->request->getParam(self::DATASET_KEY);
+		if ($value === null) {
+			return new JSONResponse(data: ['success' => true, 'config' => []]);
+		}
+
+		// The step is not `multiple`, but the wizard's contract allows a list, so
+		// both shapes are read rather than one of them reaching `(string)`.
+		$submitted = $value;
+		if (is_array($value) === true) {
+			$submitted = ($value[0] ?? null);
+		}
+
+		if (is_scalar($submitted) === false) {
+			return new JSONResponse(
+				data: ['success' => false, 'message' => 'A dataset is named by a string.'],
+				statusCode: Http::STATUS_BAD_REQUEST,
+			);
+		}
+
+		$datasetId = (string)$submitted;
+		$known     = array_column($this->demoDataService->listChoices(), 'id');
+		if (in_array($datasetId, $known, true) === false) {
+			return new JSONResponse(
+				data: ['success' => false, 'message' => 'No dataset is called "' . $datasetId . '".'],
+				statusCode: Http::STATUS_BAD_REQUEST,
+			);
+		}
+
+		$this->appConfig->setValueString(Application::APP_ID, self::DATASET_KEY, $datasetId);
+
+		return new JSONResponse(data: ['success' => true, 'config' => [self::DATASET_KEY => $datasetId]]);
+
+	}//end saveConfig()
+
 	/**
 	 * Run a privileged server-side setup action.
 	 *
@@ -125,15 +196,23 @@ public function status(): JSONResponse {
 	 */
 	#[AuthorizedAdminSetting(LaunchPadAdmin::class)]
 	public function runAction(string $actionId): JSONResponse {
-		if ($actionId === 'install-demo-data') {
-			return $this->installDemoData();
+		// `install-demo-data` is the id the step used before it asked WHICH
+		// dataset, and it still means "import the one this app ships". Kept so
+		// an older manifest, a runbook or a script that posts it keeps working.
+		if ($actionId === 'load-demo-data' || $actionId === 'install-demo-data') {
+			return $this->loadDataset(actionId: $actionId);
 		}
 
 		// DECLINING IS AN ANSWER — see DEMO_DECIDED_KEY.
+		//
+		// 🔴 AND IT ANSWERS *BOTH* STEPS. The wizard now has a choice step and a
+		// run-action step; closing only the second leaves the first outstanding,
+		// and CnAppRoot opens the wizard while ANY optional step is outstanding.
 		if ($actionId === 'skip-demo-data') {
+			$this->appConfig->setValueString(Application::APP_ID, self::DATASET_KEY, DemoDataService::NONE_DATASET);
 			$this->appConfig->setValueString(Application::APP_ID, self::DEMO_DECIDED_KEY, 'skipped');
 
-			return new JSONResponse(data: ['success' => true, 'message' => 'Demo data skipped.']);
+			return new JSONResponse(data: ['success' => true, 'message' => 'No example data was loaded.']);
 		}
 
 		return new JSONResponse(
@@ -144,15 +223,42 @@ public function runAction(string $actionId): JSONResponse {
 	}//end runAction()
 
 	/**
-	 * Import the shipped demo dataset.
+	 * Import the dataset the operator picked in the previous step.
+	 *
+	 * @param string $actionId The action that asked, which decides whether an
+	 *                         unanswered choice is refused or means the shipped set.
 	 *
 	 * Reports the FAILURE rather than a quiet success: an operator who asked for
 	 * demo data and got none must be told, which is why DemoDataService::install()
 	 * throws instead of returning an empty result.
 	 *
 	 * @return JSONResponse `{ success, message }`.
 	 */
-	private function installDemoData(): JSONResponse {
+	private function loadDataset(string $actionId): JSONResponse {
+		$picked = $this->appConfig->getValueString(Application::APP_ID, self::DATASET_KEY, '');
+
+		// The legacy id carries no answer, so it means the shipped dataset. A
+		// caller that posts it has said which one by posting it.
+		if ($actionId === 'install-demo-data' && $picked === '') {
+			$picked = DemoDataService::DEMO_DATASET;
+		}
+
+		// 🔴 NO SILENT DEFAULT. Importing here because the operator clicked Run
+		// one step early would plant example objects nobody asked for, which is
+		// the failure this whole step exists to avoid.
+		if ($picked === '') {
+			return new JSONResponse(
+				data: ['success' => false, 'message' => 'Pick a dataset first.'],
+				statusCode: Http::STATUS_BAD_REQUEST,
+			);
+		}
+
+		if ($picked === DemoDataService::NONE_DATASET) {
+			$this->appConfig->setValueString(Application::APP_ID, self::DEMO_DECIDED_KEY, 'skipped');
+
+			return new JSONResponse(data: ['success' => true, 'message' => 'No example data was loaded.']);
+		}
+
 		try {
 			$imported = $this->demoDataService->install();
 		} catch (\Throwable $e) {
@@ -176,5 +282,5 @@ private function installDemoData(): JSONResponse {
 			]
 		);
 
-	}//end installDemoData()
+	}//end loadDataset()
 }//end class

lib/Controller/SetupController.php

@@ -84,6 +84,108 @@ public function isAvailable(): bool {
 		return is_file($this->descriptorPath()) === true;
 	}//end isAvailable()
 
+	/**
+	 * The answer that means "plant nothing".
+	 *
+	 * 🔴 NOT THE ABSENCE OF AN ANSWER. An operator who declines has FINISHED the
+	 * step; a step that can never be marked done reopens the wizard over every
+	 * page (nextcloud-vue#806).
+	 *
+	 * @var string
+	 */
+	public const NONE_DATASET = 'none';
+
+	/**
+	 * The id of the dataset this app ships.
+	 *
+	 * @var string
+	 */
+	public const DEMO_DATASET = 'demo';
+
+	/**
+	 * Every answer the wizard's choice step may offer, declining included.
+	 *
+	 * 🔴 THE SERVER OWNS THIS LIST, AND THAT IS THE POINT. The step declares
+	 * `optionsSource: datasets` and no options of its own, so the label, the
+	 * description and the object count come from the descriptor that will
+	 * actually be imported. A manifest that restated them could disagree with
+	 * what lands, and nothing would notice.
+	 *
+	 * @return array<int, array{id: string, label: string, description: string, objectCount: integer, icon: string}> The answers.
+	 *
+	 * @spec exclude Demo-data choice list; ADR-111 rule 1 has no per-app behavioural spec.
+	 */
+	public function listChoices(): array {
+		$choices = [
+			[
+				'id'          => self::NONE_DATASET,
+				'label'       => 'None, I will set this up myself',
+				'description' => 'Nothing is imported. You start with an empty app and add your own data.',
+				'objectCount' => 0,
+				'icon'        => 'CloseCircleOutline',
+			],
+		];
+
+		$objects = $this->shippedObjectCount();
+		if ($objects !== null) {
+			$choices[] = [
+				'id'    => self::DEMO_DATASET,
+				'label' => 'Example data',
+				// 🔴 NO NUMBER IN THIS SENTENCE. The wizard runs a card's
+				// description through the app's translation function, which is a
+				// literal lookup, so an interpolated count would make the string
+				// untranslatable and leave a Dutch operator reading English. The
+				// count travels as `objectCount` and the card renders it as a
+				// stat, with a label the library translates.
+				'description' => (
+					'Sample values for every schema this app supplies, generated from the schemas '
+					. 'themselves. It shows the lists, detail pages and dashboards working rather '
+					. 'than telling a story. Safe to run more than once, and you can delete it '
+					. 'afterwards.'
+				),
+				'objectCount' => $objects,
+				'icon'        => 'DatabaseOutline',
+			];
+		}
+
+		return $choices;
+
+	}//end listChoices()
+
+	/**
+	 * How many objects the shipped descriptor carries, or null when it ships none.
+	 *
+	 * Counted from the FILE, so the card promises the number that will actually
+	 * be imported. A missing or malformed descriptor returns null and the app
+	 * then offers only "None" — honest, rather than an import that cannot run.
+	 *
+	 * @return integer|null The object count, or null when there is no usable descriptor.
+	 */
+	private function shippedObjectCount(): ?int {
+		$path = $this->descriptorPath();
+		if (is_file($path) === false) {
+			return null;
+		}
+
+		$raw = file_get_contents($path);
+		if ($raw === false) {
+			return null;
+		}
+
+		$data = json_decode($raw, true);
+		if (is_array($data) === false) {
+			return null;
+		}
+
+		$components = ($data['components'] ?? []);
+		if (is_array($components) === false || is_array(($components['objects'] ?? null)) === false) {
+			return 0;
+		}
+
+		return count($components['objects']);
+
+	}//end shippedObjectCount()
+
 	/**
 	 * Import the demo dataset.
 	 *