From da1f26168442716fb22c7225cb92574dacc55057 Mon Sep 17 00:00:00 2001
From: Philipp Wagner
Date: Wed, 18 Nov 2026 20:14:16 +0100
Subject: [PATCH] Remove the executed setup wizard stage 1 plan
Stage 1 is implemented and manually checked. What was worth keeping is in the commit messages, the spec and docs/PROJECT_CONTEXT.md.
Written-by: Claude Fable 5.2
---
...026-11-18-einrichtungsassistent-stufe-1.md | 2694 -----------------
1 file changed, 2694 deletions(-)
delete mode 100644 docs/superpowers/plans/2026-11-18-einrichtungsassistent-stufe-1.md
diff --git a/docs/superpowers/plans/2026-11-18-einrichtungsassistent-stufe-1.md b/docs/superpowers/plans/2026-11-18-einrichtungsassistent-stufe-1.md
deleted file mode 100644
index d351a53f..00000000
--- a/docs/superpowers/plans/2026-11-18-einrichtungsassistent-stufe-1.md
+++ /dev/null
@@ -1,2694 +0,0 @@
-# Einrichtungsassistent, Ausbaustufe 1 — Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Ein unkonfiguriertes Operatorprofil startet in einem Einrichtungsassistenten, der Persönliches, Anmeldung, Standort und Bänder abfragt und `preferences.xml` schreibt, bevor die Laufzeit gebaut wird.
-
-**Architecture:** Der Assistent läuft vor dem `ChatController` auf einem eigenen `ChatPreferences`-Objekt und schreibt die Datei; `startRuntime` liest sie danach wie jede gespeicherte Einstellung. Er ändert keine laufende Sitzung und berührt `SettingsDraft` nicht. Aus dem Menü wird die Laufzeit erst abgebaut, dann das selbe Profil mit dem Assistenten neu gestartet.
-
-**Tech Stack:** Java 21 (`core`), Kotlin 2.2 und Compose Multiplatform 1.8 (`app-desktop`), JUnit 5, Gradle-Wrapper.
-
-**Spec:** `docs/superpowers/specs/2026-11-18-einrichtungsassistent-design.md` — dieser Plan setzt **nur Ausbaustufe 1** um. Die Stufen 2 (Antenne, Logprogramm, Rotor, AirScout) und 3 („von Profil X übernehmen") bekommen eigene Pläne, sobald Stufe 1 steht; ihre Schritte hängen an den Formen, die hier entstehen.
-
-## Global Constraints
-
-- Gradle, nicht Maven. Java 21. Bau und Tests über `./gradlew`.
-- Quelltextkommentare und Javadoc ausschließlich Englisch. Kommunikation und Handbuch-Deutsch in neuer Rechtschreibung (`muss`, `dass`).
-- `core` erzeugt keinen Anzeigetext und kennt kein Toolkit. Die Erkennung liegt in `core`, alles Sichtbare in `app-desktop`.
-- Oberflächentexte stehen in `app-desktop/src/main/i18n/strings_en.properties` (Basis) und `strings_de.properties`. Beide Dateien bekommen jeden neuen Schlüssel. Ein Schlüssel nur in der deutschen Datei bricht den Bau.
-- Kein Apostroph in den neuen Texten: parametrisierte Texte laufen durch `MessageFormat`.
-- Bandbezeichnungen (`144 MHz`) und Kategorienamen sind Funkerkürzel und werden nicht übersetzt.
-- Rufzeichen und Locator werden gespeichert, wie sie getippt wurden, nur ohne Leerraum am Rand. Keine neue Normalisierung.
-- Nie blockierend auf dem AWT-Ereignisfaden warten. Das Fenster ist ein modaler `ComposeDialog`, geöffnet über `openOnEventThread`, wie `OperatorProfilePickerWindow`.
-- Unverändert bleiben: das Format von `preferences.xml`, das Einstellungsfenster mit seinen zwölf Reitern, `SettingsDraft.apply`, `OperatorProfileManagementService`, `praktiKSTpreferences.xml`.
-- Unkonfiguriert heißt: Rufzeichen leer, oder Rufzeichen `DO5AMF` mit Passwort `changeMe`.
-- Pflichtangaben für „Fertig" und „Speichern": Anzeigename, Rufzeichen, Passwort, Locator, mindestens ein Band, Chatkategorie.
-- Kein Commit, kein Push ohne ausdrücklichen Auftrag des Nutzers (`AGENTS.md`). Die Commit-Schritte unten gelten nur, wenn der Auftrag zur Ausführung das Committen einschließt; sonst bleiben die Änderungen im Arbeitsbaum.
-- Ein Testfehler bricht den Bau, PMD und SpotBugs nicht. Ergebnis aus der Test-XML unter `*/build/test-results/` lesen, nicht aus dem Rückgabewert.
-
-## Review Focus
-
-1. **Rufzeichen mit Zusatz oder in Kleinschrift** (`DL0TEST/P`, `DO5AMF-2`, `do5amf`): wird angenommen und unverändert gespeichert. Test in Task 2 (`callsignsWithSuffixAndLowerCaseAreAccepted`) und Task 3 (`aCallsignIsStoredAsTyped`).
-2. **Gespeicherte Chatkategorie außerhalb 1–3** (etwa 7) bei „unverändert lassen": bleibt 7, der Assistent schlägt nichts darüber. Test in Task 3 (`aKeptCategoryOutsideTheSuggestionsSurvives`).
-3. **Die Datei lässt sich nicht schreiben**: der Assistent bleibt offen und meldet es, statt sich mit „gespeichert" zu schließen. Test in Task 3 (`aFailedWriteIsReported`) und Task 5 (`aFailedSaveKeepsTheWizardOpen`).
-4. **Die Profildatei ist unlesbar**: der Assistent erscheint nicht und überschreibt nichts; der Start geht weiter wie heute. Test in Task 5 (`anUnreadableFileNeverOpensTheWizard`).
-5. **Fenster über das X geschlossen**: zählt als „Später", schreibt nichts. Test in Task 5 (`closingTheWindowCountsAsLater`).
-
----
-
-## Dateien
-
-| Datei | Aufgabe |
-|---|---|
-| `core/src/main/java/kst4contest/controller/LoginConfiguration.java` (neu) | Erkennung „unkonfiguriert" und Vorlagen-Anmeldedaten |
-| `core/src/test/java/kst4contest/controller/LoginConfigurationTest.java` (neu) | deren Tests, auch gegen die mitgelieferte Vorlage |
-| `app-desktop/src/main/kotlin/kst4contest/view/compose/wizard/SetupWizardState.kt` (neu) | Zustand, Ablauf, Prüfregeln, Schreiben der Antworten |
-| `app-desktop/src/main/kotlin/kst4contest/view/compose/wizard/SetupWizardContent.kt` (neu) | die Seiten als Composables |
-| `app-desktop/src/main/kotlin/kst4contest/view/compose/wizard/SetupWizardWindow.kt` (neu) | modaler Dialog, Ergebnis, Starter |
-| `app-desktop/src/test/kotlin/kst4contest/view/compose/wizard/*Test.kt` (neu) | Tests dazu |
-| `app-desktop/src/main/i18n/strings_en.properties`, `strings_de.properties` | neue Texte |
-| `app-desktop/src/main/java/kst4contest/view/Kst4ContestApplication.java` | Aufruf im Start, Verbinden danach, Menüaktion |
-| `app-desktop/src/main/java/kst4contest/view/ApplicationRuntimeLauncher.java` | Wunsch „Assistent zeigen", Neustart des selben Profils |
-| `app-desktop/src/main/java/kst4contest/view/ComposeMenuActions.java`, `.../compose/MainMenuBar.kt`, `.../compose/MainMenuModel.kt` | Menüeintrag |
-| `docs/PROJECT_CONTEXT.md`, `github_docs/de-Konfiguration.md`, `github_docs/en-Configuration.md` | Dokumentation |
-
----
-
-### Task 1: Erkennung eines unkonfigurierten Profils
-
-**Files:**
-- Create: `core/src/main/java/kst4contest/controller/LoginConfiguration.java`
-- Test: `core/src/test/java/kst4contest/controller/LoginConfigurationTest.java`
-
-**Interfaces:**
-- Consumes: `ChatPreferences.getStn_loginCallSign()`, `getStn_loginPassword()`, `ChatPreferences.PREFERENCE_RESOURCE`, Konstruktor `ChatPreferences(Path)`.
-- Produces:
- - `public static final String LoginConfiguration.TEMPLATE_CALLSIGN` (`"DO5AMF"`)
- - `public static final String LoginConfiguration.TEMPLATE_PASSWORD` (`"changeMe"`)
- - `public static boolean LoginConfiguration.carriesTemplateCredentials(ChatPreferences)`
- - `public static boolean LoginConfiguration.isUnconfigured(ChatPreferences)`
-
-- [ ] **Step 1: Write the failing test**
-
-```java
-package kst4contest.controller;
-
-import kst4contest.model.ChatPreferences;
-import org.junit.jupiter.api.Test;
-import org.junit.jupiter.api.io.TempDir;
-
-import java.io.IOException;
-import java.io.InputStream;
-import java.nio.file.Files;
-import java.nio.file.Path;
-import java.nio.file.StandardCopyOption;
-
-import static org.junit.jupiter.api.Assertions.assertFalse;
-import static org.junit.jupiter.api.Assertions.assertNotNull;
-import static org.junit.jupiter.api.Assertions.assertTrue;
-
-/**
- * When a profile counts as not set up yet. The setup wizard appears on exactly this
- * condition, so a wrong answer either nags a working station or leaves a newcomer alone
- * with the template's callsign.
- */
-class LoginConfigurationTest {
-
- @TempDir
- Path temporaryDirectory;
-
- private ChatPreferences preferences(String callsign, String password) {
- ChatPreferences preferences = new ChatPreferences(temporaryDirectory.resolve("unused.xml"));
- preferences.setStn_loginCallSign(callsign);
- preferences.setStn_loginPassword(password);
- return preferences;
- }
-
- @Test
- void anEmptyCallsignIsUnconfigured() {
- assertTrue(LoginConfiguration.isUnconfigured(preferences("", "secret")));
- assertTrue(LoginConfiguration.isUnconfigured(preferences(" ", "secret")));
- }
-
- @Test
- void theTemplateCredentialsAreUnconfigured() {
- ChatPreferences template = preferences("DO5AMF", "changeMe");
-
- assertTrue(LoginConfiguration.carriesTemplateCredentials(template));
- assertTrue(LoginConfiguration.isUnconfigured(template));
- }
-
- @Test
- void theTemplateCallsignWithItsOwnPasswordIsConfigured() {
- // The callsign belongs to a real operator; only the pair marks an untouched template.
- ChatPreferences owner = preferences("DO5AMF", "a-real-password");
-
- assertFalse(LoginConfiguration.carriesTemplateCredentials(owner));
- assertFalse(LoginConfiguration.isUnconfigured(owner));
- }
-
- @Test
- void aRealLoginIsConfigured() {
- assertFalse(LoginConfiguration.isUnconfigured(preferences("DL0TEST", "secret")));
- assertFalse(LoginConfiguration.isUnconfigured(preferences("DL0TEST/P", "")));
- }
-
- @Test
- void theConstantsMatchTheBundledTemplate() throws IOException {
- Path templateCopy = temporaryDirectory.resolve("template.xml");
- try (InputStream template = ChatPreferences.class
- .getResourceAsStream(ChatPreferences.PREFERENCE_RESOURCE)) {
- assertNotNull(template, "bundled resource " + ChatPreferences.PREFERENCE_RESOURCE);
- Files.copy(template, templateCopy, StandardCopyOption.REPLACE_EXISTING);
- }
-
- ChatPreferences fromTemplate = new ChatPreferences(templateCopy);
- assertTrue(fromTemplate.readPreferencesFromXmlFile());
-
- assertTrue(LoginConfiguration.carriesTemplateCredentials(fromTemplate),
- "the template's credentials changed; a fresh installation would no longer "
- + "be recognised as unconfigured");
- }
-}
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run: `./gradlew :core:test --tests 'kst4contest.controller.LoginConfigurationTest'`
-Expected: Kompilierfehler, `cannot find symbol ... LoginConfiguration`.
-
-- [ ] **Step 3: Write minimal implementation**
-
-```java
-package kst4contest.controller;
-
-import kst4contest.model.ChatPreferences;
-
-/**
- * Tells whether a profile has login credentials an operator entered.
- *
- * Two states count as unconfigured. An empty callsign is what every created or duplicated
- * profile starts with, because {@link OperatorProfileManagementService} clears the
- * credentials on purpose. The bundled template's credentials are what the root profile of a
- * fresh installation carries. Neither can log in as the operator, so neither needs a flag of
- * its own in {@code preferences.xml}.
- */
-public final class LoginConfiguration {
-
- /** Callsign shipped in {@code praktiKSTpreferences.xml}; held equal by a test. */
- public static final String TEMPLATE_CALLSIGN = "DO5AMF";
-
- /** Password shipped in {@code praktiKSTpreferences.xml}; held equal by a test. */
- public static final String TEMPLATE_PASSWORD = "changeMe";
-
- private LoginConfiguration() {
- // Utility class.
- }
-
- /**
- * Whether the preferences still hold the bundled template's credentials.
- *
- * Only the pair counts. The callsign alone belongs to a real operator.
- *
- * @param preferences preferences of the profile to judge
- * @return true for an untouched template
- */
- public static boolean carriesTemplateCredentials(final ChatPreferences preferences) {
- return TEMPLATE_CALLSIGN.equalsIgnoreCase(trimmed(preferences.getStn_loginCallSign()))
- && TEMPLATE_PASSWORD.equals(preferences.getStn_loginPassword());
- }
-
- /**
- * Whether the profile has no login an operator entered.
- *
- * @param preferences preferences of the profile to judge
- * @return true when the callsign is empty or the template's credentials are still there
- */
- public static boolean isUnconfigured(final ChatPreferences preferences) {
- return trimmed(preferences.getStn_loginCallSign()).isEmpty()
- || carriesTemplateCredentials(preferences);
- }
-
- private static String trimmed(final String value) {
- return value == null ? "" : value.trim();
- }
-}
-```
-
-- [ ] **Step 4: Run test to verify it passes**
-
-Run: `./gradlew :core:test --tests 'kst4contest.controller.LoginConfigurationTest'`
-Expected: 5 Tests, 0 Fehler in `core/build/test-results/test/TEST-kst4contest.controller.LoginConfigurationTest.xml`.
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add core/src/main/java/kst4contest/controller/LoginConfiguration.java core/src/test/java/kst4contest/controller/LoginConfigurationTest.java
-git commit -m "Detect operator profiles without entered login credentials"
-```
-
----
-
-### Task 2: Zustand und Ablauf des Assistenten
-
-**Files:**
-- Create: `app-desktop/src/main/kotlin/kst4contest/view/compose/wizard/SetupWizardState.kt`
-- Test: `app-desktop/src/test/kotlin/kst4contest/view/compose/wizard/SetupWizardStateTest.kt`
-
-**Interfaces:**
-- Consumes: `LoginConfiguration.isUnconfigured`, `LoginConfiguration.carriesTemplateCredentials` (Task 1); Getter von `ChatPreferences`.
-- Produces (alle in Paket `kst4contest.view.compose.wizard`):
- - `enum class WizardSource { NEW, KEEP }`
- - `enum class WizardPage { ENTRY, PERSONAL, LOGIN, SITE, SUMMARY }`
- - `enum class WizardBand(val label: String, val megahertz: Int)` mit `B50, B70, B144, B432, B1240, B2300, B3400, B5600, B10G`
- - `class SetupWizardState(prefs: ChatPreferences)` mit
- - `val loginSources: List`, `val stationSources: List`, `val hasEntryPage: Boolean`
- - `val loginSource: WizardSource?`, `val stationSource: WizardSource?`, `fun chooseLoginSource(WizardSource)`, `fun chooseStationSource(WizardSource)`
- - `val storedCallsign: String`, `val storedLocator: String`
- - `var language: String`, `var name: String`, `var callsign: String`, `var password: String`, `var locator: String`
- - `val bands: Set`, `fun setBand(WizardBand, Boolean)`
- - `val category: Int?`, `fun chooseCategory(Int)`, `val suggestedCategory: Int?`
- - `val secondChat: Boolean`, `fun chooseSecondChat(Boolean)`, `var secondCategory: Int?`, `val secondCategoryOptions: List`
- - `val page: WizardPage`, `val pages: List`
- - `val canGoNext: Boolean`, `val canGoBack: Boolean`, `val canFinish: Boolean`, `val mandatoryComplete: Boolean`
- - `val callsignRefused: Boolean`, `val locatorRefused: Boolean`
- - `fun next()`, `fun back()`, `fun finish()`, `fun edit(WizardPage)`
- - `val turnsOffSecondChat: Boolean`, `val leavesIntegrationsUntouched: Boolean`
- - `companion`: `val CATEGORY_NUMBERS: List`, `fun isPlausibleCallsign(String): Boolean`, `fun isLocator(String): Boolean`, `fun suggestCategory(Set): Int?`
-
-- [ ] **Step 1: Write the failing test**
-
-```kotlin
-package kst4contest.view.compose.wizard
-
-import kst4contest.model.ChatCategory
-import kst4contest.model.ChatPreferences
-import org.junit.jupiter.api.Assertions.assertEquals
-import org.junit.jupiter.api.Assertions.assertFalse
-import org.junit.jupiter.api.Assertions.assertNull
-import org.junit.jupiter.api.Assertions.assertTrue
-import org.junit.jupiter.api.Test
-import java.nio.file.Path
-
-/**
- * The wizard's rules without a window: which pages appear, what they start with, and when
- * the operator may go on. Nothing here reads or writes a file.
- */
-class SetupWizardStateTest {
-
- /** Preferences that never touch a file: the path is only read by read/write calls. */
- private fun prefs(configure: ChatPreferences.() -> Unit = {}): ChatPreferences =
- ChatPreferences(Path.of("setup-wizard-state-test-unused.xml")).apply(configure)
-
- private fun freshInstallation() = prefs {
- setStn_loginCallSign("DO5AMF")
- setStn_loginPassword("changeMe")
- setStn_loginNameMainCat("KST4Contest1263")
- setStn_loginLocatorMainCat("JO54ME")
- setStn_bandActive144(true)
- setLoginChatCategoryMain(ChatCategory(2))
- setLoginToSecondChatEnabled(true)
- setLoginChatCategorySecond(ChatCategory(3))
- }
-
- private fun duplicatedProfile() = prefs {
- setStn_loginCallSign("")
- setStn_loginPassword("")
- setStn_loginNameMainCat("Other Operator")
- setStn_loginLocatorMainCat("JO50AA")
- setStn_bandActive144(true)
- setStn_bandActive432(true)
- setLoginChatCategoryMain(ChatCategory(2))
- setLoginToSecondChatEnabled(false)
- }
-
- private fun configuredProfile() = duplicatedProfile().apply {
- setStn_loginCallSign("DL0TEST")
- setStn_loginPassword("secret")
- setStn_loginNameMainCat("Philipp")
- }
-
- /** Fills every mandatory answer of a first installation, leaving the wizard on SITE. */
- private fun SetupWizardState.fillFirstInstallation() {
- name = "Philipp"
- next()
- callsign = "DL0TEST"
- password = "secret"
- next()
- locator = "JO50AA"
- setBand(WizardBand.B144, true)
- }
-
- @Test
- fun aFreshInstallationHasNoEntryPageAndStartsEmpty() {
- val state = SetupWizardState(freshInstallation())
-
- assertFalse(state.hasEntryPage)
- assertEquals(WizardPage.PERSONAL, state.page)
- assertEquals(
- listOf(WizardPage.PERSONAL, WizardPage.LOGIN, WizardPage.SITE, WizardPage.SUMMARY),
- state.pages,
- )
- assertEquals("", state.name, "the template's name is nobody's name")
- assertEquals("", state.callsign)
- assertEquals("", state.locator)
- assertTrue(state.bands.isEmpty())
- assertNull(state.category)
- assertFalse(state.secondChat)
- }
-
- @Test
- fun aDuplicatedProfileIsAskedOnlyAboutTheStation() {
- val state = SetupWizardState(duplicatedProfile())
-
- assertEquals(listOf(WizardSource.NEW), state.loginSources)
- assertEquals(listOf(WizardSource.NEW, WizardSource.KEEP), state.stationSources)
- assertTrue(state.hasEntryPage)
- assertEquals(WizardPage.ENTRY, state.page)
- assertEquals(WizardSource.NEW, state.loginSource, "a single option is chosen already")
- assertNull(state.stationSource, "nothing is preselected where there is a choice")
- assertFalse(state.canGoNext)
- }
-
- @Test
- fun aConfiguredProfileMayKeepBoth() {
- val state = SetupWizardState(configuredProfile())
-
- assertEquals(listOf(WizardSource.NEW, WizardSource.KEEP), state.loginSources)
- assertEquals(listOf(WizardSource.NEW, WizardSource.KEEP), state.stationSources)
- assertEquals("Philipp", state.name, "a configured profile keeps its operator's name")
- }
-
- @Test
- fun keepingTheStationSkipsItsStepAndCarriesTheStoredValues() {
- val state = SetupWizardState(duplicatedProfile())
- state.chooseStationSource(WizardSource.KEEP)
- state.next()
-
- assertEquals(
- listOf(WizardPage.ENTRY, WizardPage.PERSONAL, WizardPage.LOGIN, WizardPage.SUMMARY),
- state.pages,
- )
- assertEquals("JO50AA", state.locator)
- assertEquals(setOf(WizardBand.B144, WizardBand.B432), state.bands)
- assertEquals(2, state.category)
- }
-
- @Test
- fun aNewStationStartsEmptyEvenOnAProfileThatHasOne() {
- val state = SetupWizardState(duplicatedProfile())
- state.chooseStationSource(WizardSource.NEW)
- state.next()
-
- assertEquals("", state.locator)
- assertTrue(state.bands.isEmpty())
- assertNull(state.category)
- assertTrue(state.pages.contains(WizardPage.SITE))
- }
-
- @Test
- fun goingBackToTheEntryPageAndOnAgainKeepsWhatWasTyped() {
- val state = SetupWizardState(duplicatedProfile())
- state.chooseStationSource(WizardSource.NEW)
- state.next()
- state.name = "Philipp"
- state.back()
- state.next()
-
- assertEquals("Philipp", state.name)
-
- state.next()
- state.callsign = "DL0TEST"
- state.back()
- state.back()
- state.chooseStationSource(WizardSource.KEEP)
- state.next()
-
- assertEquals("JO50AA", state.locator, "a changed source loads its own values")
- state.next()
- assertEquals("DL0TEST", state.callsign, "the login source did not change")
- }
-
- @Test
- fun callsignsWithSuffixAndLowerCaseAreAccepted() {
- listOf("DL0TEST", "DL0TEST/P", "DO5AMF-2", "do5amf", " DL0TEST ").forEach {
- assertTrue(SetupWizardState.isPlausibleCallsign(it), "'$it' must be accepted")
- }
- listOf("", "DL", "ABC", "123", "DL0 TEST", "DL0TEST|X", "DL0-TEST-2", "DL0TEST/").forEach {
- assertFalse(SetupWizardState.isPlausibleCallsign(it), "'$it' must be refused")
- }
- }
-
- @Test
- fun onlyASixCharacterLocatorIsAccepted() {
- listOf("JO50AA", "jo50aa", " JN49FL ").forEach {
- assertTrue(SetupWizardState.isLocator(it), "'$it' must be accepted")
- }
- listOf("", "JO50", "JO50AAA", "SS50AA", "JO50YY", "JO5OAA").forEach {
- assertFalse(SetupWizardState.isLocator(it), "'$it' must be refused")
- }
- }
-
- @Test
- fun theCategoryIsSuggestedFromTheLowestBand() {
- assertNull(SetupWizardState.suggestCategory(emptySet()))
- assertEquals(1, SetupWizardState.suggestCategory(setOf(WizardBand.B50, WizardBand.B144)))
- assertEquals(1, SetupWizardState.suggestCategory(setOf(WizardBand.B70)))
- assertEquals(2, SetupWizardState.suggestCategory(setOf(WizardBand.B144, WizardBand.B1240)))
- assertEquals(2, SetupWizardState.suggestCategory(setOf(WizardBand.B432)))
- assertEquals(3, SetupWizardState.suggestCategory(setOf(WizardBand.B1240, WizardBand.B10G)))
- }
-
- @Test
- fun theSuggestionFollowsTheBandsUntilTheOperatorChooses() {
- val state = SetupWizardState(freshInstallation())
-
- state.setBand(WizardBand.B1240, true)
- assertEquals(3, state.category)
-
- state.setBand(WizardBand.B144, true)
- assertEquals(2, state.category)
-
- state.chooseCategory(3)
- state.setBand(WizardBand.B50, true)
- assertEquals(3, state.category, "an operator's choice is not overwritten")
- assertEquals(1, state.suggestedCategory, "the suggestion is still shown")
- }
-
- @Test
- fun aSecondChatNeedsADifferentCategory() {
- val state = SetupWizardState(freshInstallation())
- state.fillFirstInstallation()
- assertTrue(state.canGoNext)
-
- state.chooseSecondChat(true)
- assertFalse(state.canGoNext, "the second chat has no category yet")
- assertFalse(state.secondCategoryOptions.contains(2), "the main category is not offered twice")
-
- state.secondCategory = 3
- assertTrue(state.canGoNext)
-
- state.chooseCategory(3)
- assertNull(state.secondCategory, "the same chat cannot be opened twice")
- assertFalse(state.canGoNext)
- }
-
- @Test
- fun finishNeedsEveryMandatoryAnswer() {
- val state = SetupWizardState(freshInstallation())
-
- state.name = "Philipp"
- assertFalse(state.canFinish)
- state.next()
- state.callsign = "DL0TEST"
- state.password = "secret"
- assertFalse(state.canFinish, "a new station still lacks its locator")
- state.next()
- state.locator = "JO50AA"
- assertFalse(state.canFinish, "no band yet")
- state.setBand(WizardBand.B144, true)
- assertTrue(state.canFinish)
-
- state.finish()
- assertEquals(WizardPage.SUMMARY, state.page)
- assertTrue(state.mandatoryComplete)
- assertFalse(state.canFinish, "the summary has Save instead")
- }
-
- @Test
- fun aKeptStationLetsTheOperatorFinishAfterTheLogin() {
- val state = SetupWizardState(duplicatedProfile())
- state.chooseStationSource(WizardSource.KEEP)
- state.next()
- state.name = "Philipp"
- state.next()
- state.callsign = "DL0TEST/P"
- state.password = "secret"
-
- assertTrue(state.canFinish)
- }
-
- @Test
- fun aRefusedEntryIsOnlyShownOnceSomethingWasTyped() {
- val state = SetupWizardState(freshInstallation())
-
- assertFalse(state.callsignRefused, "an empty field is not an error yet")
- state.callsign = "DL"
- assertTrue(state.callsignRefused)
- state.callsign = "DL0TEST"
- assertFalse(state.callsignRefused)
-
- assertFalse(state.locatorRefused)
- state.locator = "JO50"
- assertTrue(state.locatorRefused)
- }
-
- @Test
- fun changeFromTheSummaryOpensAStepThatWasSkipped() {
- val state = SetupWizardState(configuredProfile())
- state.chooseLoginSource(WizardSource.KEEP)
- state.chooseStationSource(WizardSource.KEEP)
- state.next()
- state.next()
- assertEquals(WizardPage.SUMMARY, state.page)
-
- state.edit(WizardPage.LOGIN)
-
- assertEquals(WizardPage.LOGIN, state.page)
- assertEquals("DL0TEST", state.callsign, "the kept value is there to be changed")
- state.callsign = "DL0TEST/P"
- state.next()
- assertEquals(WizardPage.SUMMARY, state.page)
- }
-
- @Test
- fun theSummarySaysWhatIsSwitchedOffAndWhatIsLeftAlone() {
- val fresh = SetupWizardState(freshInstallation())
- assertTrue(fresh.turnsOffSecondChat, "the template has the second chat on, a new station has it off")
- assertTrue(fresh.leavesIntegrationsUntouched)
-
- val kept = SetupWizardState(duplicatedProfile())
- kept.chooseStationSource(WizardSource.KEEP)
- kept.next()
- assertFalse(kept.turnsOffSecondChat)
- assertFalse(kept.leavesIntegrationsUntouched)
- }
-}
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run: `./gradlew :app-desktop:test --tests 'kst4contest.view.compose.wizard.SetupWizardStateTest'`
-Expected: Kompilierfehler, `Unresolved reference: SetupWizardState`.
-
-- [ ] **Step 3: Write minimal implementation**
-
-```kotlin
-package kst4contest.view.compose.wizard
-
-import androidx.compose.runtime.getValue
-import androidx.compose.runtime.mutableStateOf
-import androidx.compose.runtime.setValue
-import kst4contest.controller.LoginConfiguration
-import kst4contest.model.ChatCategory
-import kst4contest.model.ChatPreferences
-
-/** Where the answers of one group come from. */
-enum class WizardSource {
- /** Entered in the wizard, starting from the wizard's own empty values. */
- NEW,
-
- /** What the profile already holds. */
- KEEP,
-}
-
-/** The pages, in the order they can appear. */
-enum class WizardPage { ENTRY, PERSONAL, LOGIN, SITE, SUMMARY }
-
-/**
- * A band the station can be active on.
- *
- * The labels are amateur shorthand and deliberately not in the translation files.
- */
-enum class WizardBand(
- val label: String,
- val megahertz: Int,
- internal val isActive: (ChatPreferences) -> Boolean,
- internal val setActive: (ChatPreferences, Boolean) -> Unit,
-) {
- B50("50 MHz", 50, { it.isStn_bandActive50() }, { p, on -> p.setStn_bandActive50(on) }),
- B70("70 MHz", 70, { it.isStn_bandActive70() }, { p, on -> p.setStn_bandActive70(on) }),
- B144("144 MHz", 144, { it.isStn_bandActive144() }, { p, on -> p.setStn_bandActive144(on) }),
- B432("432 MHz", 432, { it.isStn_bandActive432() }, { p, on -> p.setStn_bandActive432(on) }),
- B1240("1240 MHz", 1240, { it.isStn_bandActive1240() }, { p, on -> p.setStn_bandActive1240(on) }),
- B2300("2300 MHz", 2300, { it.isStn_bandActive2300() }, { p, on -> p.setStn_bandActive2300(on) }),
- B3400("3400 MHz", 3400, { it.isStn_bandActive3400() }, { p, on -> p.setStn_bandActive3400(on) }),
- B5600("5600 MHz", 5600, { it.isStn_bandActive5600() }, { p, on -> p.setStn_bandActive5600(on) }),
- B10G("10 GHz", 10000, { it.isStn_bandActive10G() }, { p, on -> p.setStn_bandActive10G(on) }),
-}
-
-/**
- * The setup wizard's answers and the rules of its course, free of any window.
- *
- * It reads the preferences once, when it is built, and does not touch them again until
- * [writeTo]: closing the wizard without saving therefore leaves the profile exactly as it
- * was. The design is in `docs/superpowers/specs/2026-11-18-einrichtungsassistent-design.md`.
- *
- * The answers are Compose state, so a composition reading them follows; nothing else here
- * depends on Compose.
- *
- * @param prefs the profile's preferences, already read from its file
- */
-class SetupWizardState(prefs: ChatPreferences) {
-
- private val loginConfigured = !LoginConfiguration.isUnconfigured(prefs)
- private val templateCredentials = LoginConfiguration.carriesTemplateCredentials(prefs)
-
- /** The callsign the profile holds, for the label of "leave unchanged". */
- val storedCallsign: String = prefs.getStn_loginCallSign().orEmpty()
- private val storedPassword: String = prefs.getStn_loginPassword().orEmpty()
- private val storedName: String = prefs.getStn_loginNameMainCat().orEmpty()
- private val storedSecondName: String = prefs.getStn_loginNameSecondCat().orEmpty()
-
- /** The locator the profile holds, for the label of "leave unchanged". */
- val storedLocator: String = prefs.getStn_loginLocatorMainCat().orEmpty()
- private val storedBands: Set = WizardBand.entries.filter { it.isActive(prefs) }.toSet()
- private val storedCategory: Int? = prefs.getLoginChatCategoryMain()?.categoryNumber
- private val storedSecondChat: Boolean = prefs.isLoginToSecondChatEnabled()
- private val storedSecondCategory: Int? = prefs.getLoginChatCategorySecond()?.categoryNumber
-
- /** A login can only be kept where an operator entered one. */
- val loginSources: List = buildList {
- add(WizardSource.NEW)
- if (loginConfigured) add(WizardSource.KEEP)
- }
-
- /**
- * A station can be kept unless the profile is the untouched template: its locator and
- * bands are then nobody's.
- */
- val stationSources: List = buildList {
- add(WizardSource.NEW)
- if (!templateCredentials) add(WizardSource.KEEP)
- }
-
- /** Whether there is anything to choose on the entry page. */
- val hasEntryPage: Boolean = loginSources.size > 1 || stationSources.size > 1
-
- var loginSource: WizardSource? by mutableStateOf(loginSources.singleOrNull())
- private set
-
- var stationSource: WizardSource? by mutableStateOf(stationSources.singleOrNull())
- private set
-
- private var appliedLoginSource: WizardSource? = null
- private var appliedStationSource: WizardSource? = null
-
- /** The stored form of the language: a code, or empty for the system language. */
- var language: String by mutableStateOf(prefs.getGuiOptions_language().orEmpty())
-
- /** Empty on an unconfigured profile: its stored name is the template's or another operator's. */
- var name: String by mutableStateOf(if (loginConfigured) storedName else "")
-
- var callsign: String by mutableStateOf("")
- var password: String by mutableStateOf("")
- var locator: String by mutableStateOf("")
-
- var bands: Set by mutableStateOf(emptySet())
- private set
-
- var category: Int? by mutableStateOf(null)
- private set
-
- private var categoryChosenByOperator = false
-
- var secondChat: Boolean by mutableStateOf(false)
- private set
-
- var secondCategory: Int? by mutableStateOf(null)
-
- private var loginShown by mutableStateOf(false)
- private var stationShown by mutableStateOf(false)
-
- var page: WizardPage by mutableStateOf(if (hasEntryPage) WizardPage.ENTRY else WizardPage.PERSONAL)
- private set
-
- init {
- if (!hasEntryPage) applySources()
- }
-
- fun chooseLoginSource(source: WizardSource) {
- if (source in loginSources) loginSource = source
- }
-
- fun chooseStationSource(source: WizardSource) {
- if (source in stationSources) stationSource = source
- }
-
- /**
- * Loads the answers of a group whose source changed. A group whose source is the one
- * already applied is left alone, so going back to the entry page costs nothing typed.
- */
- private fun applySources() {
- if (loginSource != appliedLoginSource) {
- val keep = loginSource == WizardSource.KEEP
- callsign = if (keep) storedCallsign else ""
- password = if (keep) storedPassword else ""
- loginShown = !keep
- appliedLoginSource = loginSource
- }
-
- if (stationSource != appliedStationSource) {
- val keep = stationSource == WizardSource.KEEP
- locator = if (keep) storedLocator else ""
- bands = if (keep) storedBands else emptySet()
- category = if (keep) storedCategory else null
- secondChat = keep && storedSecondChat
- secondCategory = if (keep) storedSecondCategory else null
- // A kept category is the operator's; the suggestion must not replace it.
- categoryChosenByOperator = keep
- stationShown = !keep
- appliedStationSource = stationSource
- }
- }
-
- fun setBand(band: WizardBand, active: Boolean) {
- bands = if (active) bands + band else bands - band
- if (!categoryChosenByOperator) setCategory(suggestCategory(bands))
- }
-
- /** What the bands suggest, shown beside the picker whatever is chosen. */
- val suggestedCategory: Int?
- get() = suggestCategory(bands)
-
- fun chooseCategory(number: Int) {
- categoryChosenByOperator = true
- setCategory(number)
- }
-
- private fun setCategory(number: Int?) {
- category = number
- if (secondCategory == number) secondCategory = null
- }
-
- fun chooseSecondChat(enabled: Boolean) {
- secondChat = enabled
- }
-
- /** The main category is left out, as the Station tab does. */
- val secondCategoryOptions: List
- get() = CATEGORY_NUMBERS.filter { it != category }
-
- /** The pages of this run, in order. */
- val pages: List
- get() = buildList {
- if (hasEntryPage) add(WizardPage.ENTRY)
- add(WizardPage.PERSONAL)
- if (loginShown) add(WizardPage.LOGIN)
- if (stationShown) add(WizardPage.SITE)
- add(WizardPage.SUMMARY)
- }
-
- private val personalComplete: Boolean
- get() = name.isNotBlank()
-
- private val loginComplete: Boolean
- get() = isPlausibleCallsign(callsign) && password.isNotEmpty()
-
- private val stationComplete: Boolean
- get() = isLocator(locator) && bands.isNotEmpty() && category != null &&
- (!secondChat || (secondCategory != null && secondCategory != category))
-
- /** Whether everything the profile needs to log in is there. */
- val mandatoryComplete: Boolean
- get() = personalComplete && loginComplete && stationComplete
-
- /** A callsign that was typed and does not look like one. An empty field is not an error yet. */
- val callsignRefused: Boolean
- get() = callsign.isNotBlank() && !isPlausibleCallsign(callsign)
-
- /** A locator that was typed and is not one. An empty field is not an error yet. */
- val locatorRefused: Boolean
- get() = locator.isNotBlank() && !isLocator(locator)
-
- val canGoNext: Boolean
- get() = when (page) {
- WizardPage.ENTRY -> loginSource != null && stationSource != null
- WizardPage.PERSONAL -> personalComplete
- WizardPage.LOGIN -> loginComplete
- WizardPage.SITE -> stationComplete
- WizardPage.SUMMARY -> false
- }
-
- val canGoBack: Boolean
- get() = pages.indexOf(page) > 0
-
- /**
- * Whether the remaining steps may be skipped. Only with every mandatory answer, because
- * a summary that cannot be saved helps nobody.
- */
- val canFinish: Boolean
- get() = page != WizardPage.ENTRY && page != WizardPage.SUMMARY && mandatoryComplete
-
- fun next() {
- if (!canGoNext) return
- if (page == WizardPage.ENTRY) applySources()
- page = pages[pages.indexOf(page) + 1]
- }
-
- fun back() {
- if (canGoBack) page = pages[pages.indexOf(page) - 1]
- }
-
- fun finish() {
- if (canFinish) page = WizardPage.SUMMARY
- }
-
- /** Opens a step from the summary, also one this run skipped. */
- fun edit(target: WizardPage) {
- when (target) {
- WizardPage.LOGIN -> loginShown = true
- WizardPage.SITE -> stationShown = true
- WizardPage.PERSONAL -> Unit
- WizardPage.ENTRY, WizardPage.SUMMARY -> return
- }
- page = target
- }
-
- /** The profile had a second chat and will have none. */
- val turnsOffSecondChat: Boolean
- get() = storedSecondChat && !secondChat
-
- /**
- * A new station is set up, and this stage does not ask about log program, rotator,
- * AirScout and DX cluster server: they keep their stored values, and the summary says so.
- */
- val leavesIntegrationsUntouched: Boolean
- get() = stationSource == WizardSource.NEW
-
- companion object {
-
- /** The categories the pickers offer, the way the Station tab builds them. */
- val CATEGORY_NUMBERS: List = ChatCategory(0).possibleCategoryNumbers.toList()
-
- private val CALLSIGN = Regex("[A-Za-z0-9]+([-/][A-Za-z0-9]+)?")
- private val LOCATOR = Regex("[A-Ra-r]{2}[0-9]{2}[A-Xa-x]{2}")
-
- /**
- * Whether a text can be a login callsign: letters and digits, at most one "-" or "/"
- * suffix, and a base of three characters with a letter and a digit. Deliberately
- * loose -- ON4KST decides what it accepts, this only catches a slip.
- */
- fun isPlausibleCallsign(text: String): Boolean {
- val trimmed = text.trim()
- if (!CALLSIGN.matches(trimmed)) return false
- val base = trimmed.substringBefore('-').substringBefore('/')
- return base.length >= 3 && base.any(Char::isDigit) && base.any(Char::isLetter)
- }
-
- /** Whether a text is a six-character Maidenhead locator, in either case. */
- fun isLocator(text: String): Boolean = LOCATOR.matches(text.trim())
-
- /**
- * The chat category the lowest band belongs to: 1 for 50/70 MHz, 2 for 144/432 MHz,
- * 3 above. Null without a band. A suggestion only -- the operator confirms it.
- */
- fun suggestCategory(bands: Set): Int? {
- val lowest = bands.minOfOrNull { it.megahertz } ?: return null
- return when {
- lowest <= 70 -> ChatCategory.FIFTYSEVENTYMHz
- lowest <= 432 -> ChatCategory.VUHF
- else -> ChatCategory.MICROWAVE
- }
- }
- }
-}
-```
-
-- [ ] **Step 4: Run test to verify it passes**
-
-Run: `./gradlew :app-desktop:test --tests 'kst4contest.view.compose.wizard.SetupWizardStateTest'`
-Expected: 16 Tests, 0 Fehler in `app-desktop/build/test-results/test/TEST-kst4contest.view.compose.wizard.SetupWizardStateTest.xml`.
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add app-desktop/src/main/kotlin/kst4contest/view/compose/wizard/SetupWizardState.kt app-desktop/src/test/kotlin/kst4contest/view/compose/wizard/SetupWizardStateTest.kt
-git commit -m "Add setup wizard state and its course rules"
-```
-
----
-
-### Task 3: Antworten in die Profildatei schreiben
-
-**Files:**
-- Modify: `app-desktop/src/main/kotlin/kst4contest/view/compose/wizard/SetupWizardState.kt` (Methode `writeTo` vor dem `companion object` ergänzen)
-- Test: `app-desktop/src/test/kotlin/kst4contest/view/compose/wizard/SetupWizardWriteTest.kt`
-
-**Interfaces:**
-- Consumes: `SetupWizardState` aus Task 2; Setter und `writePreferencesToXmlFile()` von `ChatPreferences`.
-- Produces: `fun SetupWizardState.writeTo(prefs: ChatPreferences): Boolean` — setzt die Antworten und schreibt die Datei; `false`, wenn Pflichtangaben fehlen oder das Schreiben scheitert. Bei fehlenden Pflichtangaben wird `prefs` nicht angefasst.
-
-- [ ] **Step 1: Write the failing test**
-
-```kotlin
-package kst4contest.view.compose.wizard
-
-import kst4contest.model.ChatCategory
-import kst4contest.model.ChatPreferences
-import org.junit.jupiter.api.Assertions.assertArrayEquals
-import org.junit.jupiter.api.Assertions.assertEquals
-import org.junit.jupiter.api.Assertions.assertFalse
-import org.junit.jupiter.api.Assertions.assertTrue
-import org.junit.jupiter.api.Test
-import org.junit.jupiter.api.io.TempDir
-import java.nio.file.Files
-import java.nio.file.Path
-import java.nio.file.StandardCopyOption
-
-/**
- * What the wizard does to a real preferences file: nothing until Save, exactly the answers
- * afterwards, and every setting it never asked about left as it was.
- */
-class SetupWizardWriteTest(@TempDir private val directory: Path) {
-
- /** A copy of the bundled template, read the way the runtime reads a profile. */
- private fun templateFile(): Path {
- val file = directory.resolve("preferences.xml")
- ChatPreferences::class.java.getResourceAsStream(ChatPreferences.PREFERENCE_RESOURCE).use { template ->
- Files.copy(requireNotNull(template), file, StandardCopyOption.REPLACE_EXISTING)
- }
- return file
- }
-
- private fun read(file: Path): ChatPreferences =
- ChatPreferences(file).also { assertTrue(it.readPreferencesFromXmlFile(), "reading $file failed") }
-
- /** A profile an operator set up: read the template, change it, write it back. */
- private fun configuredFile(change: ChatPreferences.() -> Unit = {}): Path {
- val file = templateFile()
- read(file).apply {
- setStn_loginCallSign("DL0TEST")
- setStn_loginPassword("secret")
- setStn_loginNameMainCat("Philipp")
- setStn_loginNameSecondCat("Philipp")
- setStn_loginLocatorMainCat("JO50AA")
- setStn_bandActive144(true)
- setLoginChatCategoryMain(ChatCategory(2))
- setLoginToSecondChatEnabled(false)
- change()
- assertTrue(writePreferencesToXmlFile())
- }
- return file
- }
-
- private fun SetupWizardState.answerFirstInstallation() {
- name = "Philipp"
- next()
- callsign = "DL0TEST"
- password = "secret"
- next()
- locator = "JO50AA"
- setBand(WizardBand.B144, true)
- setBand(WizardBand.B1240, true)
- finish()
- }
-
- @Test
- fun nothingIsWrittenBeforeSave() {
- val file = templateFile()
- val prefs = read(file)
- // Taken after the read, so only the wizard is measured here.
- val before = Files.readAllBytes(file)
-
- SetupWizardState(prefs).answerFirstInstallation()
-
- assertArrayEquals(before, Files.readAllBytes(file), "the file changed without Save")
- assertEquals("DO5AMF", prefs.getStn_loginCallSign(), "the preferences changed without Save")
- }
-
- @Test
- fun saveWritesExactlyTheAnswers() {
- val file = templateFile()
- val prefs = read(file)
- val state = SetupWizardState(prefs)
- state.answerFirstInstallation()
-
- assertTrue(state.writeTo(prefs))
-
- val restored = read(file)
- assertEquals("DL0TEST", restored.getStn_loginCallSign())
- assertEquals("secret", restored.getStn_loginPassword())
- assertEquals("Philipp", restored.getStn_loginNameMainCat())
- assertEquals("JO50AA", restored.getStn_loginLocatorMainCat())
- assertTrue(restored.isStn_bandActive144())
- assertTrue(restored.isStn_bandActive1240())
- assertFalse(restored.isStn_bandActive432(), "a band the operator did not tick is off")
- assertEquals(2, restored.getLoginChatCategoryMain().categoryNumber)
- assertFalse(restored.isLoginToSecondChatEnabled(), "a new station starts without a second chat")
- }
-
- @Test
- fun whatTheWizardNeverAskedAboutIsLeftAsItWas() {
- val file = templateFile()
- val prefs = read(file)
- val server = prefs.getStn_on4kstServersDns()
- val rotatorPort = prefs.getStn_pstRotatorPort()
- val udpListener = prefs.isLogsynch_ucxUDPWkdCallListenerEnabled()
- val clusterServer = prefs.isNotify_dxClusterServerEnabled()
- val airScout = prefs.isAirScout_asUDPListenerEnabled()
- val beamWidth = prefs.getStn_antennaBeamWidthDeg()
-
- val state = SetupWizardState(prefs)
- state.answerFirstInstallation()
- assertTrue(state.writeTo(prefs))
-
- val restored = read(file)
- assertEquals(server, restored.getStn_on4kstServersDns())
- assertEquals(rotatorPort, restored.getStn_pstRotatorPort())
- assertEquals(udpListener, restored.isLogsynch_ucxUDPWkdCallListenerEnabled())
- assertEquals(clusterServer, restored.isNotify_dxClusterServerEnabled())
- assertEquals(airScout, restored.isAirScout_asUDPListenerEnabled())
- assertEquals(beamWidth, restored.getStn_antennaBeamWidthDeg())
- }
-
- @Test
- fun aCallsignIsStoredAsTyped() {
- val file = templateFile()
- val prefs = read(file)
- val state = SetupWizardState(prefs)
- state.name = "Philipp"
- state.next()
- state.callsign = " do5amf-2 "
- state.password = "secret"
- state.next()
- state.locator = " jo50aa "
- state.setBand(WizardBand.B144, true)
-
- assertTrue(state.writeTo(prefs))
-
- val restored = read(file)
- assertEquals("do5amf-2", restored.getStn_loginCallSign(), "only the surrounding blanks go")
- assertEquals("jo50aa", restored.getStn_loginLocatorMainCat(), "the Station tab stores it as typed too")
- }
-
- @Test
- fun aKeptCategoryOutsideTheSuggestionsSurvives() {
- val file = configuredFile {
- setLoginChatCategoryMain(ChatCategory(7))
- setLoginToSecondChatEnabled(true)
- setLoginChatCategorySecond(ChatCategory(9))
- }
- val prefs = read(file)
- val state = SetupWizardState(prefs)
- state.chooseLoginSource(WizardSource.KEEP)
- state.chooseStationSource(WizardSource.KEEP)
- state.next()
- state.next()
-
- assertTrue(state.writeTo(prefs))
-
- val restored = read(file)
- assertEquals(7, restored.getLoginChatCategoryMain().categoryNumber)
- assertTrue(restored.isLoginToSecondChatEnabled())
- assertEquals(9, restored.getLoginChatCategorySecond().categoryNumber)
- }
-
- @Test
- fun theSecondNameFollowsTheFirstUnlessItWasSetApart() {
- val following = configuredFile()
- val prefs = read(following)
- val state = SetupWizardState(prefs)
- state.chooseLoginSource(WizardSource.KEEP)
- state.chooseStationSource(WizardSource.KEEP)
- state.next()
- state.name = "Marc"
- state.next()
- assertTrue(state.writeTo(prefs))
- assertEquals("Marc", read(following).getStn_loginNameSecondCat())
-
- val apart = configuredFile { setStn_loginNameSecondCat("Philipp SHF") }
- val apartPrefs = read(apart)
- val apartState = SetupWizardState(apartPrefs)
- apartState.chooseLoginSource(WizardSource.KEEP)
- apartState.chooseStationSource(WizardSource.KEEP)
- apartState.next()
- apartState.name = "Marc"
- apartState.next()
- assertTrue(apartState.writeTo(apartPrefs))
- assertEquals("Philipp SHF", read(apart).getStn_loginNameSecondCat(), "a name set apart is the operator's")
- }
-
- @Test
- fun anUntouchedLanguageStaysEvenIfThisBuildDoesNotKnowIt() {
- val file = configuredFile { setGuiOptions_language("fr") }
- val prefs = read(file)
- val state = SetupWizardState(prefs)
- state.chooseLoginSource(WizardSource.KEEP)
- state.chooseStationSource(WizardSource.KEEP)
- state.next()
- state.next()
-
- assertTrue(state.writeTo(prefs))
-
- assertEquals("fr", read(file).getGuiOptions_language())
- }
-
- @Test
- fun incompleteAnswersAreNotWritten() {
- val file = templateFile()
- val prefs = read(file)
- val before = Files.readAllBytes(file)
- val state = SetupWizardState(prefs)
- state.name = "Philipp"
-
- assertFalse(state.writeTo(prefs))
-
- assertArrayEquals(before, Files.readAllBytes(file))
- assertEquals("DO5AMF", prefs.getStn_loginCallSign())
- }
-
- @Test
- fun aFailedWriteIsReported() {
- val source = read(templateFile())
- // A directory where the file should be: the write cannot succeed.
- val unwritable = ChatPreferences(Files.createDirectory(directory.resolve("not-a-file")))
- val state = SetupWizardState(source)
- state.answerFirstInstallation()
-
- assertFalse(state.writeTo(unwritable), "a write that failed must not read as saved")
- }
-}
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run: `./gradlew :app-desktop:test --tests 'kst4contest.view.compose.wizard.SetupWizardWriteTest'`
-Expected: Kompilierfehler, `Unresolved reference: writeTo`.
-
-- [ ] **Step 3: Write minimal implementation**
-
-In `SetupWizardState.kt` unmittelbar vor `companion object {` einfügen:
-
-```kotlin
- /**
- * Puts the answers into [prefs] and writes its file.
- *
- * Everything the wizard did not ask about stays as [prefs] read it, because the whole
- * file is read and written back. The callsign and the locator are stored as typed, the
- * way the Station tab stores them; only surrounding blanks go.
- *
- * The second chat's name follows the first unless the operator had set it apart, and the
- * second category is left alone while the second chat is off.
- *
- * @return false when a mandatory answer is missing -- nothing is touched then -- or when
- * the file could not be written
- */
- fun writeTo(prefs: ChatPreferences): Boolean {
- if (!mandatoryComplete) return false
-
- val newName = name.trim()
-
- prefs.setGuiOptions_language(language)
- prefs.setStn_loginNameMainCat(newName)
- if (storedSecondName.isBlank() || storedSecondName == storedName) {
- prefs.setStn_loginNameSecondCat(newName)
- }
-
- prefs.setStn_loginCallSign(callsign.trim())
- prefs.setStn_loginPassword(password)
-
- prefs.setStn_loginLocatorMainCat(locator.trim())
- WizardBand.entries.forEach { it.setActive(prefs, it in bands) }
- prefs.setLoginChatCategoryMain(ChatCategory(requireNotNull(category)))
- prefs.setLoginToSecondChatEnabled(secondChat)
- if (secondChat) {
- prefs.setLoginChatCategorySecond(ChatCategory(requireNotNull(secondCategory)))
- }
-
- // A write that throws is a write that failed; the wizard must stay open either way.
- return runCatching { prefs.writePreferencesToXmlFile() }.getOrDefault(false)
- }
-```
-
-- [ ] **Step 4: Run test to verify it passes**
-
-Run: `./gradlew :app-desktop:test --tests 'kst4contest.view.compose.wizard.SetupWizardWriteTest'`
-Expected: 9 Tests, 0 Fehler in `app-desktop/build/test-results/test/TEST-kst4contest.view.compose.wizard.SetupWizardWriteTest.xml`.
-
-Schlägt `aFailedWriteIsReported` fehl, weil `writePreferencesToXmlFile` für ein Verzeichnis `true` liefert: **nicht** den Test abschwächen. Den Befund melden — dann meldet auch „Save settings" im Einstellungsfenster einen Erfolg, den es nicht gab, und das ist ein eigener Fehler in `ChatPreferences`.
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add app-desktop/src/main/kotlin/kst4contest/view/compose/wizard/SetupWizardState.kt app-desktop/src/test/kotlin/kst4contest/view/compose/wizard/SetupWizardWriteTest.kt
-git commit -m "Write setup wizard answers to the profile's preferences file"
-```
-
----
-
-### Task 4: Die Seiten des Assistenten
-
-**Files:**
-- Create: `app-desktop/src/main/kotlin/kst4contest/view/compose/wizard/SetupWizardContent.kt`
-- Modify: `app-desktop/src/main/i18n/strings_en.properties`, `app-desktop/src/main/i18n/strings_de.properties` (Schlüssel am Dateiende anfügen)
-- Test: `app-desktop/src/test/kotlin/kst4contest/view/compose/wizard/SetupWizardContentScreenTest.kt`
-
-**Interfaces:**
-- Consumes: `SetupWizardState`, `WizardPage`, `WizardSource`, `WizardBand` (Task 2); `Form`, `Density`, `Kst4ContestTheme` aus `kst4contest.view.compose`; `LanguageStore`, `LocalStrings`, `Strings`, `Translations`, `SYSTEM_LANGUAGE` aus `kst4contest.view.i18n`; vorhandene Texte `stationCallsign`, `stationPassword`, `stationLocator`, `stationMainCategory`, `stationSecondCategory`, `guiLanguage`, `guiLanguageSystem`.
-- Produces:
- - `@Composable fun SetupWizardContent(state: SetupWizardState, languageStore: LanguageStore, saveFailed: Boolean, onLater: () -> Unit, onSave: (connect: Boolean) -> Unit)`
- - `fun wizardLanguageStore(state: SetupWizardState): LanguageStore` — ein `LanguageStore`, dessen Wahl in `state.language` landet und nicht in den Einstellungen
- - die Textschlüssel `wizard.*` (als `strings.wizard…` erzeugt)
-
-- [ ] **Step 1: Texte anlegen**
-
-An das Ende von `app-desktop/src/main/i18n/strings_en.properties` anfügen:
-
-```properties
-wizard.title=Setup assistant
-wizard.later=Later
-wizard.back=Back
-wizard.next=Next
-wizard.finish=Finish
-wizard.save=Save
-wizard.saveAndConnect=Save and connect
-wizard.change=Change
-wizard.saveFailed=The settings could not be written. Nothing was changed.
-wizard.missing=Some required entries are still missing. Use Change to complete them.
-wizard.entry.title=Where do the entries come from?
-wizard.entry.lead=Choose separately for login and station.
-wizard.entry.login=Login (callsign, password)
-wizard.entry.station=Station (locator, bands, chat category)
-wizard.source.loginNew=Enter a new login
-wizard.source.loginKeep=Leave the login unchanged ({0})
-wizard.source.stationNew=Set up a new station
-wizard.source.stationKeep=Leave the station unchanged (locator {0})
-wizard.personal.title=Personal
-wizard.personal.lead=Belongs to the operator.
-wizard.personal.name=Name shown in the chat
-wizard.login.title=ON4KST login
-wizard.login.lead=The credentials of your ON4KST account.
-wizard.login.callsignInvalid=This does not look like a callsign.
-wizard.site.title=Location and bands
-wizard.site.lead=Belongs to the station, not to the operator.
-wizard.site.locatorInvalid=Six-character Maidenhead locator, for example JO50AA.
-wizard.site.bands=Active bands
-wizard.site.bandsHint=No frequency is derived from the bands.
-wizard.site.categorySuggestion=Suggested from the bands: {0}
-wizard.site.secondChat=Open a second chat
-wizard.summary.title=Summary
-wizard.summary.lead=Nothing is written until you save.
-wizard.summary.personal=Personal
-wizard.summary.login=Login
-wizard.summary.station=Station
-wizard.summary.bands=Bands
-wizard.summary.turnedOff=Will be switched off: second chat.
-wizard.summary.integrationsUnchanged=Log program, rotator, AirScout and DX cluster server keep their stored settings. Check them in the settings window.
-wizard.summary.none=none
-wizard.summary.passwordSet=set
-```
-
-An das Ende von `app-desktop/src/main/i18n/strings_de.properties` anfügen:
-
-```properties
-wizard.title=Einrichtungsassistent
-wizard.later=Später
-wizard.back=Zurück
-wizard.next=Weiter
-wizard.finish=Fertig
-wizard.save=Speichern
-wizard.saveAndConnect=Speichern und verbinden
-wizard.change=Ändern
-wizard.saveFailed=Die Einstellungen konnten nicht geschrieben werden. Es wurde nichts geändert.
-wizard.missing=Es fehlen noch Pflichtangaben. Über „Ändern" ergänzen.
-wizard.entry.title=Woher kommen die Angaben?
-wizard.entry.lead=Für Anmeldung und Station getrennt wählen.
-wizard.entry.login=Anmeldung (Rufzeichen, Passwort)
-wizard.entry.station=Station (Locator, Bänder, Chatkategorie)
-wizard.source.loginNew=Anmeldung neu eingeben
-wizard.source.loginKeep=Anmeldung unverändert lassen ({0})
-wizard.source.stationNew=Station neu einrichten
-wizard.source.stationKeep=Station unverändert lassen (Locator {0})
-wizard.personal.title=Persönliches
-wizard.personal.lead=Gehört zum Operator.
-wizard.personal.name=Anzeigename im Chat
-wizard.login.title=Anmeldung bei ON4KST
-wizard.login.lead=Die Zugangsdaten deines ON4KST-Kontos.
-wizard.login.callsignInvalid=Das sieht nicht nach einem Rufzeichen aus.
-wizard.site.title=Standort und Bänder
-wizard.site.lead=Gehört zur Station, nicht zum Operator.
-wizard.site.locatorInvalid=Sechsstelliger Maidenhead-Locator, zum Beispiel JO50AA.
-wizard.site.bands=Aktive Bänder
-wizard.site.bandsHint=Aus den Bändern wird keine Frequenz abgeleitet.
-wizard.site.categorySuggestion=Vorschlag aus den Bändern: {0}
-wizard.site.secondChat=Zweiten Chat öffnen
-wizard.summary.title=Zusammenfassung
-wizard.summary.lead=Erst „Speichern" schreibt in die Einstellungsdatei.
-wizard.summary.personal=Persönliches
-wizard.summary.login=Anmeldung
-wizard.summary.station=Station
-wizard.summary.bands=Bänder
-wizard.summary.turnedOff=Wird abgeschaltet: Zweitchat.
-wizard.summary.integrationsUnchanged=Logprogramm, Rotor, AirScout und DX-Cluster-Server behalten ihre gespeicherten Werte. Im Einstellungsfenster prüfen.
-wizard.summary.none=keine
-wizard.summary.passwordSet=gesetzt
-```
-
-Run: `./gradlew :app-desktop:compileKotlin`
-Expected: BUILD SUCCESSFUL. Ein Fehler des Erzeugers nennt den Schlüssel; er prüft doppelte Schlüssel, Waisen und die Zahl der Platzhalter.
-
-- [ ] **Step 2: Write the failing test**
-
-```kotlin
-package kst4contest.view.compose.wizard
-
-import androidx.compose.ui.test.ComposeUiTest
-import androidx.compose.ui.test.ExperimentalTestApi
-import androidx.compose.ui.test.onNodeWithText
-import androidx.compose.ui.test.performClick
-import androidx.compose.ui.test.runComposeUiTest
-import kst4contest.model.ChatCategory
-import kst4contest.model.ChatPreferences
-import kst4contest.view.compose.Kst4ContestTheme
-import kst4contest.view.i18n.LanguageStore
-import org.junit.jupiter.api.Assertions.assertEquals
-import org.junit.jupiter.api.Assertions.assertTrue
-import org.junit.jupiter.api.Test
-import java.nio.file.Path
-import java.util.Locale
-
-/**
- * The drawn wizard, clicked the way an operator clicks it. The rules live in
- * SetupWizardState and are tested there; this holds the wiring -- that a button reaches the
- * state, and that a button which must not work does not.
- */
-@OptIn(ExperimentalTestApi::class)
-class SetupWizardContentScreenTest {
-
- private fun configuredProfile() =
- ChatPreferences(Path.of("setup-wizard-screen-test-unused.xml")).apply {
- setStn_loginCallSign("DL0TEST")
- setStn_loginPassword("secret")
- setStn_loginNameMainCat("Philipp")
- setStn_loginLocatorMainCat("JO50AA")
- setStn_bandActive144(true)
- setLoginChatCategoryMain(ChatCategory(2))
- // Stated, not left to the compiled-in default: with a second chat and no second
- // category the summary could not be saved.
- setLoginToSecondChatEnabled(false)
- }
-
- private class Recorded {
- var later = 0
- val saves = mutableListOf()
- }
-
- private fun ComposeUiTest.show(state: SetupWizardState, saveFailed: Boolean = false): Recorded {
- val recorded = Recorded()
- // English, whatever language an earlier test in this JVM left behind.
- val english = LanguageStore({ "en" }, {}, Locale.ENGLISH)
- setContent {
- Kst4ContestTheme(darkMode = false, baseFontSizeSp = 12f) {
- SetupWizardContent(
- state = state,
- languageStore = english,
- saveFailed = saveFailed,
- onLater = { recorded.later++ },
- onSave = { recorded.saves += it },
- )
- }
- }
- return recorded
- }
-
- @Test
- fun nextDoesNothingUntilBothSourcesAreChosen() = runComposeUiTest {
- val state = SetupWizardState(configuredProfile())
- show(state)
-
- onNodeWithText("Next").performClick()
- assertEquals(WizardPage.ENTRY, state.page, "Next worked without a choice")
-
- onNodeWithText("Leave the login unchanged (DL0TEST)").performClick()
- onNodeWithText("Leave the station unchanged (locator JO50AA)").performClick()
- assertEquals(WizardSource.KEEP, state.loginSource)
- assertEquals(WizardSource.KEEP, state.stationSource)
-
- onNodeWithText("Next").performClick()
- assertEquals(WizardPage.PERSONAL, state.page)
- }
-
- @Test
- fun laterIsReportedAndNothingElse() = runComposeUiTest {
- val recorded = show(SetupWizardState(configuredProfile()))
-
- onNodeWithText("Later").performClick()
-
- assertEquals(1, recorded.later)
- assertTrue(recorded.saves.isEmpty())
- }
-
- @Test
- fun theSummaryOffersBothWaysOfSaving() = runComposeUiTest {
- val state = SetupWizardState(configuredProfile())
- state.chooseLoginSource(WizardSource.KEEP)
- state.chooseStationSource(WizardSource.KEEP)
- state.next()
- state.next()
- val recorded = show(state)
-
- onNodeWithText("Save").performClick()
- onNodeWithText("Save and connect").performClick()
-
- assertEquals(listOf(false, true), recorded.saves)
- }
-
- @Test
- fun aFailedSaveIsToldToTheOperator() = runComposeUiTest {
- val state = SetupWizardState(configuredProfile())
- state.chooseLoginSource(WizardSource.KEEP)
- state.chooseStationSource(WizardSource.KEEP)
- state.next()
- state.next()
- show(state, saveFailed = true)
-
- onNodeWithText("The settings could not be written. Nothing was changed.").assertExists()
- }
-}
-```
-
-- [ ] **Step 3: Run test to verify it fails**
-
-Run: `./gradlew :app-desktop:test --tests 'kst4contest.view.compose.wizard.SetupWizardContentScreenTest'`
-Expected: Kompilierfehler, `Unresolved reference: SetupWizardContent`.
-
-- [ ] **Step 4: Write minimal implementation**
-
-```kotlin
-package kst4contest.view.compose.wizard
-
-import androidx.compose.foundation.layout.Arrangement
-import androidx.compose.foundation.layout.Column
-import androidx.compose.foundation.layout.Row
-import androidx.compose.foundation.layout.Spacer
-import androidx.compose.foundation.layout.fillMaxSize
-import androidx.compose.foundation.layout.fillMaxWidth
-import androidx.compose.foundation.layout.padding
-import androidx.compose.foundation.rememberScrollState
-import androidx.compose.foundation.selection.selectable
-import androidx.compose.foundation.verticalScroll
-import androidx.compose.material3.MaterialTheme
-import androidx.compose.material3.RadioButton
-import androidx.compose.material3.Surface
-import androidx.compose.material3.Text
-import androidx.compose.runtime.Composable
-import androidx.compose.runtime.CompositionLocalProvider
-import androidx.compose.ui.Alignment
-import androidx.compose.ui.Modifier
-import androidx.compose.ui.semantics.Role
-import androidx.compose.ui.unit.dp
-import kst4contest.model.ChatCategory
-import kst4contest.view.compose.Density
-import kst4contest.view.compose.Form
-import kst4contest.view.i18n.LanguageStore
-import kst4contest.view.i18n.LocalStrings
-import kst4contest.view.i18n.SYSTEM_LANGUAGE
-import kst4contest.view.i18n.Strings
-import kst4contest.view.i18n.Translations
-
-/**
- * A language store for the wizard: a choice takes effect on screen at once and is kept in
- * the wizard's answers, not in the preferences. "Later" therefore stores no language, and
- * the runtime built afterwards puts the stored one back in force.
- */
-fun wizardLanguageStore(state: SetupWizardState): LanguageStore =
- LanguageStore(storedLanguage = { state.language }, storeLanguage = { state.language = it })
-
-/** The name a chat category carries in the pickers, the one the Station tab shows. */
-private fun categoryName(number: Int): String = ChatCategory(number).getChatCategoryName(number)
-
-/**
- * The wizard's pages and its button row.
- *
- * All decisions are in [state]; this draws them. The texts are read from [languageStore] in
- * the composition, so the language picker on the first page switches the wizard itself.
- *
- * @param saveFailed whether the last Save could not write the file
- * @param onLater the operator does not want to set up now; nothing is written
- * @param onSave the operator saves; true when the session should be started afterwards
- */
-@Composable
-fun SetupWizardContent(
- state: SetupWizardState,
- languageStore: LanguageStore,
- saveFailed: Boolean,
- onLater: () -> Unit,
- onSave: (connect: Boolean) -> Unit,
-) {
- val strings = languageStore.strings
-
- CompositionLocalProvider(LocalStrings provides strings) {
- Surface(modifier = Modifier.fillMaxSize()) {
- Column(modifier = Modifier.padding(15.dp)) {
- Column(
- modifier = Modifier.weight(1f).fillMaxWidth().verticalScroll(rememberScrollState()),
- verticalArrangement = Arrangement.spacedBy(6.dp),
- ) {
- when (state.page) {
- WizardPage.ENTRY -> EntryPage(state, strings)
- WizardPage.PERSONAL -> PersonalPage(state, strings, languageStore)
- WizardPage.LOGIN -> LoginPage(state, strings)
- WizardPage.SITE -> SitePage(state, strings)
- WizardPage.SUMMARY -> SummaryPage(state, strings, saveFailed)
- }
- }
-
- Row(
- modifier = Modifier.fillMaxWidth().padding(top = 10.dp),
- horizontalArrangement = Arrangement.spacedBy(Density.BUTTON_GAP),
- ) {
- Form.button(strings.wizardLater, onClick = onLater)
- Spacer(Modifier.weight(1f))
- if (state.canGoBack) {
- Form.button(strings.wizardBack, onClick = state::back)
- }
- if (state.page == WizardPage.SUMMARY) {
- Form.button(strings.wizardSave, enabled = state.mandatoryComplete) { onSave(false) }
- Form.button(
- strings.wizardSaveAndConnect,
- enabled = state.mandatoryComplete,
- accented = true,
- ) { onSave(true) }
- } else {
- if (state.canFinish) {
- Form.button(strings.wizardFinish, onClick = state::finish)
- }
- Form.button(
- strings.wizardNext,
- enabled = state.canGoNext,
- accented = true,
- onClick = state::next,
- )
- }
- }
- }
- }
- }
-}
-
-@Composable
-private fun Heading(title: String, lead: String) {
- Text(title, style = MaterialTheme.typography.titleMedium)
- Text(lead, style = MaterialTheme.typography.bodySmall)
-}
-
-@Composable
-private fun Refusal(text: String) {
- Text(text, color = MaterialTheme.colorScheme.error, style = MaterialTheme.typography.bodySmall)
-}
-
-@Composable
-private fun SourceOption(label: String, selected: Boolean, onSelect: () -> Unit) {
- Row(
- modifier = Modifier
- .fillMaxWidth()
- .selectable(selected = selected, role = Role.RadioButton, onClick = onSelect)
- .padding(vertical = 2.dp),
- verticalAlignment = Alignment.CenterVertically,
- ) {
- RadioButton(selected = selected, onClick = null)
- Text(label, modifier = Modifier.padding(start = 6.dp))
- }
-}
-
-@Composable
-private fun EntryPage(state: SetupWizardState, strings: Strings) {
- Heading(strings.wizardEntryTitle, strings.wizardEntryLead)
-
- /* An axis with a single option is decided already and is not asked about. */
- if (state.loginSources.size > 1) {
- Form.section(strings.wizardEntryLogin) {
- state.loginSources.forEach { source ->
- SourceOption(
- label = when (source) {
- WizardSource.NEW -> strings.wizardSourceLoginNew
- WizardSource.KEEP -> strings.wizardSourceLoginKeep(state.storedCallsign)
- },
- selected = state.loginSource == source,
- onSelect = { state.chooseLoginSource(source) },
- )
- }
- }
- }
-
- if (state.stationSources.size > 1) {
- Form.section(strings.wizardEntryStation) {
- state.stationSources.forEach { source ->
- SourceOption(
- label = when (source) {
- WizardSource.NEW -> strings.wizardSourceStationNew
- WizardSource.KEEP -> strings.wizardSourceStationKeep(state.storedLocator)
- },
- selected = state.stationSource == source,
- onSelect = { state.chooseStationSource(source) },
- )
- }
- }
- }
-}
-
-@Composable
-private fun PersonalPage(state: SetupWizardState, strings: Strings, languageStore: LanguageStore) {
- Heading(strings.wizardPersonalTitle, strings.wizardPersonalLead)
-
- Form.choice(
- label = strings.guiLanguage,
- items = listOf(SYSTEM_LANGUAGE) + Translations.BY_LANGUAGE.keys.sorted(),
- selected = languageStore.stored,
- // The code in capitals, as the GUI tab shows it.
- describe = { code -> if (code == SYSTEM_LANGUAGE) strings.guiLanguageSystem else code.uppercase() },
- onSelect = { languageStore.use(it) },
- )
- Form.text(strings.wizardPersonalName, state.name) { state.name = it }
-}
-
-@Composable
-private fun LoginPage(state: SetupWizardState, strings: Strings) {
- Heading(strings.wizardLoginTitle, strings.wizardLoginLead)
-
- Form.text(strings.stationCallsign, state.callsign) { state.callsign = it }
- if (state.callsignRefused) Refusal(strings.wizardLoginCallsignInvalid)
- Form.password(strings.stationPassword, state.password) { state.password = it }
-}
-
-@Composable
-private fun SitePage(state: SetupWizardState, strings: Strings) {
- Heading(strings.wizardSiteTitle, strings.wizardSiteLead)
-
- Form.text(strings.stationLocator, state.locator) { state.locator = it }
- if (state.locatorRefused) Refusal(strings.wizardSiteLocatorInvalid)
-
- Form.flowingSection(strings.wizardSiteBands) {
- WizardBand.entries.forEach { band ->
- Form.check(band.label, band in state.bands) { state.setBand(band, it) }
- }
- }
- Text(strings.wizardSiteBandsHint, style = MaterialTheme.typography.bodySmall)
-
- Form.choice(
- label = strings.stationMainCategory,
- items = SetupWizardState.CATEGORY_NUMBERS,
- selected = state.category,
- describe = ::categoryName,
- onSelect = state::chooseCategory,
- )
- state.suggestedCategory?.let { suggested ->
- Text(
- strings.wizardSiteCategorySuggestion(categoryName(suggested)),
- style = MaterialTheme.typography.bodySmall,
- )
- }
-
- Form.check(strings.wizardSiteSecondChat, state.secondChat) { state.chooseSecondChat(it) }
- if (state.secondChat) {
- Form.choice(
- label = strings.stationSecondCategory,
- items = state.secondCategoryOptions,
- selected = state.secondCategory,
- describe = ::categoryName,
- onSelect = { state.secondCategory = it },
- )
- }
-}
-
-@Composable
-private fun SummaryRow(label: String, value: String) {
- Form.labelledRow(label) { Text(value) }
-}
-
-@Composable
-private fun SummaryPage(state: SetupWizardState, strings: Strings, saveFailed: Boolean) {
- Heading(strings.wizardSummaryTitle, strings.wizardSummaryLead)
-
- if (saveFailed) Refusal(strings.wizardSaveFailed)
- if (!state.mandatoryComplete) Refusal(strings.wizardMissing)
- if (state.turnsOffSecondChat) Text(strings.wizardSummaryTurnedOff)
- if (state.leavesIntegrationsUntouched) Text(strings.wizardSummaryIntegrationsUnchanged)
-
- Form.section(strings.wizardSummaryPersonal) {
- SummaryRow(strings.wizardPersonalName, state.name.ifBlank { strings.wizardSummaryNone })
- Form.button(strings.wizardChange) { state.edit(WizardPage.PERSONAL) }
- }
-
- Form.section(strings.wizardSummaryLogin) {
- SummaryRow(strings.stationCallsign, state.callsign.ifBlank { strings.wizardSummaryNone })
- // Never the password itself: the summary may be read over a shoulder.
- SummaryRow(
- strings.stationPassword,
- if (state.password.isEmpty()) strings.wizardSummaryNone else strings.wizardSummaryPasswordSet,
- )
- Form.button(strings.wizardChange) { state.edit(WizardPage.LOGIN) }
- }
-
- Form.section(strings.wizardSummaryStation) {
- SummaryRow(strings.stationLocator, state.locator.ifBlank { strings.wizardSummaryNone })
- SummaryRow(
- strings.wizardSummaryBands,
- WizardBand.entries.filter { it in state.bands }.joinToString(", ") { it.label }
- .ifEmpty { strings.wizardSummaryNone },
- )
- SummaryRow(
- strings.stationMainCategory,
- state.category?.let(::categoryName) ?: strings.wizardSummaryNone,
- )
- SummaryRow(
- strings.stationSecondCategory,
- state.secondCategory?.takeIf { state.secondChat }?.let(::categoryName) ?: strings.wizardSummaryNone,
- )
- Form.button(strings.wizardChange) { state.edit(WizardPage.SITE) }
- }
-}
-```
-
-- [ ] **Step 5: Run test to verify it passes**
-
-Run: `./gradlew :app-desktop:test --tests 'kst4contest.view.compose.wizard.SetupWizardContentScreenTest'`
-Expected: 4 Tests, 0 Fehler.
-
-Meldet der Übersetzer, dass `Density.BUTTON_GAP` oder `Form.labelledRow` nicht sichtbar ist: beide werden in `OperatorProfilePickerWindow.kt` bzw. `FormControls.kt` im Paket `kst4contest.view.compose` benutzt. Ist eines davon `internal`, bleibt es das — der Assistent liegt im selben Modul.
-
-- [ ] **Step 6: Die Sprachtests laufen lassen**
-
-Run: `./gradlew :app-desktop:test --tests 'kst4contest.view.i18n.*'`
-Expected: alle grün. `TranslationBoundaryTest` hält Deutsch vollständig; ein fehlender deutscher Schlüssel fällt hier auf.
-
-- [ ] **Step 7: Commit**
-
-```bash
-git add app-desktop/src/main/kotlin/kst4contest/view/compose/wizard/SetupWizardContent.kt app-desktop/src/main/i18n/strings_en.properties app-desktop/src/main/i18n/strings_de.properties app-desktop/src/test/kotlin/kst4contest/view/compose/wizard/SetupWizardContentScreenTest.kt
-git commit -m "Draw the setup wizard pages"
-```
-
----
-
-### Task 5: Fenster und Starter
-
-**Files:**
-- Create: `app-desktop/src/main/kotlin/kst4contest/view/compose/wizard/SetupWizardWindow.kt`
-- Test: `app-desktop/src/test/kotlin/kst4contest/view/compose/wizard/SetupWizardLauncherTest.kt`
-- Test: `app-desktop/src/test/kotlin/kst4contest/view/compose/wizard/SetupWizardWindowTest.kt`
-
-**Interfaces:**
-- Consumes: `SetupWizardState`, `writeTo` (Task 2, 3); `SetupWizardContent`, `wizardLanguageStore` (Task 4); `LoginConfiguration.isUnconfigured` (Task 1); `openOnEventThread`, `Kst4ContestTheme`, `WindowPlacementOnScreen.centreOnMainWindowScreen` aus `kst4contest.view.compose`; Testhelfer `kst4contest.testing.Await.awaitUntil`.
-- Produces:
- - `enum class SetupWizardOutcome { NOT_SHOWN, LATER, SAVED, SAVED_AND_CONNECT }`
- - `object SetupWizardWindow { fun show(state: SetupWizardState, prefs: ChatPreferences): SetupWizardOutcome }` — blockiert, bis das Fenster zu ist
- - `object SetupWizardLauncher` mit
- - `@JvmStatic fun runIfNeeded(preferencesRelativeFileName: String, forced: Boolean): SetupWizardOutcome`
- - `internal fun run(prefs: ChatPreferences, forced: Boolean, show: (SetupWizardState, ChatPreferences) -> SetupWizardOutcome): SetupWizardOutcome`
- - `internal fun saveFromWizard(state: SetupWizardState, prefs: ChatPreferences, connect: Boolean): SetupWizardOutcome?` — `null`, wenn das Schreiben scheiterte
-
-- [ ] **Step 1: Write the failing tests**
-
-`SetupWizardLauncherTest.kt`:
-
-```kotlin
-package kst4contest.view.compose.wizard
-
-import kst4contest.model.ChatPreferences
-import org.junit.jupiter.api.Assertions.assertArrayEquals
-import org.junit.jupiter.api.Assertions.assertEquals
-import org.junit.jupiter.api.Assertions.assertNull
-import org.junit.jupiter.api.Assertions.assertTrue
-import org.junit.jupiter.api.Test
-import org.junit.jupiter.api.io.TempDir
-import java.nio.file.Files
-import java.nio.file.Path
-import java.nio.file.StandardCopyOption
-
-/** When the wizard opens at all, decided without a window. */
-class SetupWizardLauncherTest(@TempDir private val directory: Path) {
-
- private fun templateFile(): Path {
- val file = directory.resolve("preferences.xml")
- ChatPreferences::class.java.getResourceAsStream(ChatPreferences.PREFERENCE_RESOURCE).use { template ->
- Files.copy(requireNotNull(template), file, StandardCopyOption.REPLACE_EXISTING)
- }
- return file
- }
-
- private fun configuredFile(): Path {
- val file = templateFile()
- ChatPreferences(file).apply {
- assertTrue(readPreferencesFromXmlFile())
- setStn_loginCallSign("DL0TEST")
- setStn_loginPassword("secret")
- assertTrue(writePreferencesToXmlFile())
- }
- return file
- }
-
- private val neverShown: (SetupWizardState, ChatPreferences) -> SetupWizardOutcome =
- { _, _ -> throw AssertionError("the wizard must not open here") }
-
- @Test
- fun anUnconfiguredProfileOpensTheWizard() {
- var shown = 0
-
- val outcome = SetupWizardLauncher.run(ChatPreferences(templateFile()), forced = false) { _, _ ->
- shown++
- SetupWizardOutcome.LATER
- }
-
- assertEquals(1, shown)
- assertEquals(SetupWizardOutcome.LATER, outcome)
- }
-
- @Test
- fun aConfiguredProfileStartsWithoutTheWizard() {
- assertEquals(
- SetupWizardOutcome.NOT_SHOWN,
- SetupWizardLauncher.run(ChatPreferences(configuredFile()), forced = false, neverShown),
- )
- }
-
- @Test
- fun theMenuOpensItOnAConfiguredProfileToo() {
- val outcome = SetupWizardLauncher.run(ChatPreferences(configuredFile()), forced = true) { state, _ ->
- assertEquals(listOf(WizardSource.NEW, WizardSource.KEEP), state.loginSources)
- SetupWizardOutcome.SAVED
- }
-
- assertEquals(SetupWizardOutcome.SAVED, outcome)
- }
-
- @Test
- fun anUnreadableFileNeverOpensTheWizard() {
- val garbage = directory.resolve("broken.xml")
- Files.writeString(garbage, "this is not xml <<<")
- val before = Files.readAllBytes(garbage)
-
- // Forced as well: a wizard over a file it could not read would save over it.
- assertEquals(
- SetupWizardOutcome.NOT_SHOWN,
- SetupWizardLauncher.run(ChatPreferences(garbage), forced = true, neverShown),
- )
- assertArrayEquals(before, Files.readAllBytes(garbage), "the unreadable file was touched")
- }
-
- @Test
- fun aFailedSaveKeepsTheWizardOpen() {
- val source = ChatPreferences(templateFile()).apply { assertTrue(readPreferencesFromXmlFile()) }
- val state = SetupWizardState(source).apply {
- name = "Philipp"
- next()
- callsign = "DL0TEST"
- password = "secret"
- next()
- locator = "JO50AA"
- setBand(WizardBand.B144, true)
- }
- val unwritable = ChatPreferences(Files.createDirectory(directory.resolve("not-a-file")))
-
- assertNull(saveFromWizard(state, unwritable, connect = true), "a failed write must not close the wizard")
- }
-
- @Test
- fun aSaveReportsWhetherToConnect() {
- val file = templateFile()
- val prefs = ChatPreferences(file).apply { assertTrue(readPreferencesFromXmlFile()) }
- val state = SetupWizardState(prefs).apply {
- name = "Philipp"
- next()
- callsign = "DL0TEST"
- password = "secret"
- next()
- locator = "JO50AA"
- setBand(WizardBand.B144, true)
- }
-
- assertEquals(SetupWizardOutcome.SAVED, saveFromWizard(state, prefs, connect = false))
- assertEquals(SetupWizardOutcome.SAVED_AND_CONNECT, saveFromWizard(state, prefs, connect = true))
- }
-}
-```
-
-`SetupWizardWindowTest.kt`:
-
-```kotlin
-package kst4contest.view.compose.wizard
-
-import kst4contest.model.ChatPreferences
-import kst4contest.testing.Await.awaitUntil
-import org.junit.jupiter.api.Assertions.assertEquals
-import org.junit.jupiter.api.Assumptions.assumeFalse
-import org.junit.jupiter.api.Test
-import java.awt.EventQueue
-import java.awt.GraphicsEnvironment
-import java.awt.Window
-import java.nio.file.Path
-import java.time.Duration
-import java.util.concurrent.Executors
-import java.util.concurrent.Future
-import java.util.concurrent.TimeUnit
-
-/**
- * The wizard's dialog must open from both threads that open it: `main` at startup, and the
- * event thread when the menu rebuilds the runtime. A latch-based wait deadlocked the profile
- * picker in exactly the second case; see OperatorProfilePickerWindow.
- */
-class SetupWizardWindowTest {
-
- private fun prefs() = ChatPreferences(Path.of("setup-wizard-window-test-unused.xml"))
-
- private fun showingDialog(): Window? =
- Window.getWindows().firstOrNull { it.isShowing && it.javaClass.name.contains("ComposeDialog") }
-
- private val closer = Executors.newSingleThreadExecutor()
-
- /** Closes the dialog the way its X does, as soon as it is on screen. */
- private fun disposeOnceShowing(): Future<*> =
- closer.submit {
- awaitUntil(Duration.ofSeconds(10), "the wizard's dialog never appeared") {
- showingDialog() != null
- }
- EventQueue.invokeLater { showingDialog()?.dispose() }
- }
-
- @Test
- fun closingTheWindowCountsAsLater() {
- assumeFalse(GraphicsEnvironment.isHeadless(), "needs a display")
-
- try {
- val closing = disposeOnceShowing()
- val prefs = prefs()
-
- val outcome = SetupWizardWindow.show(SetupWizardState(prefs), prefs)
-
- assertEquals(SetupWizardOutcome.LATER, outcome)
- assertEquals("", prefs.getStn_loginCallSign(), "closing the window wrote something")
- closing.get(1, TimeUnit.SECONDS)
- } finally {
- closer.shutdownNow()
- }
- }
-
- @Test
- fun opensAndReturnsWhenCalledOnTheEventThread() {
- assumeFalse(GraphicsEnvironment.isHeadless(), "needs a display")
-
- val worker = Executors.newSingleThreadExecutor()
- try {
- val closing = disposeOnceShowing()
- val prefs = prefs()
- val call = worker.submit {
- EventQueue.invokeAndWait { SetupWizardWindow.show(SetupWizardState(prefs), prefs) }
- }
-
- // A deadlock here has no timeout of its own: without one this never completes.
- call.get(20, TimeUnit.SECONDS)
- closing.get(1, TimeUnit.SECONDS)
- } finally {
- worker.shutdownNow()
- closer.shutdownNow()
- }
- }
-}
-```
-
-- [ ] **Step 2: Run tests to verify they fail**
-
-Run: `./gradlew :app-desktop:test --tests 'kst4contest.view.compose.wizard.SetupWizardLauncherTest' --tests 'kst4contest.view.compose.wizard.SetupWizardWindowTest'`
-Expected: Kompilierfehler, `Unresolved reference: SetupWizardLauncher`.
-
-- [ ] **Step 3: Write minimal implementation**
-
-```kotlin
-package kst4contest.view.compose.wizard
-
-import androidx.compose.runtime.getValue
-import androidx.compose.runtime.mutableStateOf
-import androidx.compose.runtime.setValue
-import androidx.compose.ui.awt.ComposeDialog
-import kst4contest.controller.LoginConfiguration
-import kst4contest.model.ChatPreferences
-import kst4contest.view.compose.Kst4ContestTheme
-import kst4contest.view.compose.WindowPlacementOnScreen
-import kst4contest.view.compose.openOnEventThread
-import java.awt.Dialog
-import java.awt.Dimension
-import java.util.concurrent.atomic.AtomicReference
-import javax.swing.WindowConstants
-
-/** How a run of the setup wizard ended. */
-enum class SetupWizardOutcome {
- /** The profile is set up, or its file could not be read: the wizard did not open. */
- NOT_SHOWN,
-
- /** Closed without saving; the file is as it was. */
- LATER,
-
- /** The answers are in the file. */
- SAVED,
-
- /** The answers are in the file and the operator wants the session started. */
- SAVED_AND_CONNECT,
-}
-
-/**
- * Writes the answers and says how the wizard ends.
- *
- * @return the outcome to close with, or null when the file could not be written -- the
- * wizard then stays open, because "saved" would be a lie
- */
-internal fun saveFromWizard(
- state: SetupWizardState,
- prefs: ChatPreferences,
- connect: Boolean,
-): SetupWizardOutcome? =
- when {
- !state.writeTo(prefs) -> null
- connect -> SetupWizardOutcome.SAVED_AND_CONNECT
- else -> SetupWizardOutcome.SAVED
- }
-
-/**
- * The setup wizard's window.
- *
- * A modal [ComposeDialog] opened through [openOnEventThread], the construction
- * OperatorProfilePickerWindow uses and for the reason given there: a wait that does not
- * pump events deadlocks once the caller is the event thread, and this one is called from
- * `main` at startup and from the event thread when the menu rebuilds the runtime.
- */
-object SetupWizardWindow {
-
- /** Runs before a profile's runtime exists, so there is no configured size to read. */
- private const val DIALOG_FONT_SIZE_SP = 12f
-
- private val DIALOG_SIZE = Dimension(640, 620)
-
- /**
- * Opens the wizard and blocks until it is closed.
- *
- * @param prefs the profile's preferences; written only by Save
- * @return never [SetupWizardOutcome.NOT_SHOWN]
- */
- fun show(state: SetupWizardState, prefs: ChatPreferences): SetupWizardOutcome {
- /* The window's X leaves this untouched: closing is "later". */
- val outcome = AtomicReference(SetupWizardOutcome.LATER)
-
- openOnEventThread { open(state, prefs, outcome) }
-
- return outcome.get()
- }
-
- private fun open(
- state: SetupWizardState,
- prefs: ChatPreferences,
- outcome: AtomicReference,
- ) {
- val languageStore = wizardLanguageStore(state)
- var saveFailed by mutableStateOf(false)
-
- val dialog = ComposeDialog(owner = null, modalityType = Dialog.ModalityType.APPLICATION_MODAL)
- dialog.title = languageStore.strings.wizardTitle
- dialog.size = DIALOG_SIZE
- WindowPlacementOnScreen.centreOnMainWindowScreen(dialog)
- /* Disposed and not hidden: a hidden dialog keeps its window and Skia layer alive. */
- dialog.defaultCloseOperation = WindowConstants.DISPOSE_ON_CLOSE
-
- dialog.setContent {
- Kst4ContestTheme(
- darkMode = prefs.isGUI_darkModeActiveByDefault(),
- baseFontSizeSp = DIALOG_FONT_SIZE_SP,
- ) {
- SetupWizardContent(
- state = state,
- languageStore = languageStore,
- saveFailed = saveFailed,
- onLater = { dialog.dispose() },
- onSave = { connect ->
- val saved = saveFromWizard(state, prefs, connect)
- if (saved == null) {
- saveFailed = true
- } else {
- outcome.set(saved)
- dialog.dispose()
- }
- },
- )
- }
- }
-
- dialog.isVisible = true
- }
-}
-
-/** Decides whether the wizard opens for a profile, and opens it. */
-object SetupWizardLauncher {
-
- /**
- * Opens the wizard when the profile needs it, before the profile's runtime is built.
- *
- * @param preferencesRelativeFileName the profile's preferences file below the
- * application directory; a missing one is seeded from the bundled template, as
- * the runtime itself would do
- * @param forced the operator asked for the wizard from the menu
- */
- @JvmStatic
- fun runIfNeeded(preferencesRelativeFileName: String, forced: Boolean): SetupWizardOutcome =
- run(ChatPreferences(preferencesRelativeFileName), forced, SetupWizardWindow::show)
-
- /**
- * @param prefs bound to the profile's file and not read yet
- * @param show opens the window; replaced in the tests
- */
- internal fun run(
- prefs: ChatPreferences,
- forced: Boolean,
- show: (SetupWizardState, ChatPreferences) -> SetupWizardOutcome,
- ): SetupWizardOutcome {
- /*
- * A file that cannot be read is not a profile to set up: the wizard would start from
- * compiled-in defaults and Save would write them over whatever the file holds. The
- * runtime deals with such a file as it always did.
- */
- if (!prefs.readPreferencesFromXmlFile()) return SetupWizardOutcome.NOT_SHOWN
-
- if (!forced && !LoginConfiguration.isUnconfigured(prefs)) return SetupWizardOutcome.NOT_SHOWN
-
- return show(SetupWizardState(prefs), prefs)
- }
-}
-```
-
-- [ ] **Step 4: Run tests to verify they pass**
-
-Run: `./gradlew :app-desktop:test --tests 'kst4contest.view.compose.wizard.*'`
-Expected: alle Tests der vier Klassen grün; `SetupWizardWindowTest` läuft nur mit Bildschirm und wird sonst übersprungen (`skipped` in der XML, kein Fehler).
-
-Liefert `readPreferencesFromXmlFile` für die kaputte Datei `true`: den Test nicht abschwächen, den Befund melden. Dann liest `ChatPreferences` Müll als gültig, und das betrifft auch den normalen Start.
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add app-desktop/src/main/kotlin/kst4contest/view/compose/wizard/SetupWizardWindow.kt app-desktop/src/test/kotlin/kst4contest/view/compose/wizard/SetupWizardLauncherTest.kt app-desktop/src/test/kotlin/kst4contest/view/compose/wizard/SetupWizardWindowTest.kt
-git commit -m "Open the setup wizard as a modal dialog"
-```
-
----
-
-### Task 6: Der Assistent im Programmstart
-
-**Files:**
-- Modify: `app-desktop/src/main/java/kst4contest/view/ApplicationRuntimeLauncher.java`
-- Modify: `app-desktop/src/main/java/kst4contest/view/Kst4ContestApplication.java` (Methode `startRuntime`, ab Zeile 2174)
-- Test: `app-desktop/src/test/java/kst4contest/view/ApplicationRuntimeLauncherSetupWizardTest.java`
-
-**Interfaces:**
-- Consumes: `SetupWizardLauncher.runIfNeeded(String, boolean)`, `SetupWizardOutcome` (Task 5); `ActiveOperatorProfile.get().getPreferencesRelativeFileName()`; `Kst4ContestApplication.menuActionConnect()`.
-- Produces:
- - `static void ApplicationRuntimeLauncher.requestSetupWizard()` (paketsichtbar)
- - `static boolean ApplicationRuntimeLauncher.consumeSetupWizardRequest()` (paketsichtbar) — liefert den Wunsch genau einmal
-
-- [ ] **Step 1: Write the failing test**
-
-```java
-package kst4contest.view;
-
-import org.junit.jupiter.api.Test;
-
-import static org.junit.jupiter.api.Assertions.assertFalse;
-import static org.junit.jupiter.api.Assertions.assertTrue;
-
-/**
- * The request to show the setup wizard on the next runtime start is honoured exactly once.
- * A request that stuck would open the wizard on every later profile switch.
- */
-class ApplicationRuntimeLauncherSetupWizardTest {
-
- @Test
- void aRequestIsHonouredOnce() {
- assertFalse(ApplicationRuntimeLauncher.consumeSetupWizardRequest(), "nothing was requested");
-
- ApplicationRuntimeLauncher.requestSetupWizard();
-
- assertTrue(ApplicationRuntimeLauncher.consumeSetupWizardRequest());
- assertFalse(ApplicationRuntimeLauncher.consumeSetupWizardRequest(), "the request must not stick");
- }
-}
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run: `./gradlew :app-desktop:test --tests 'kst4contest.view.ApplicationRuntimeLauncherSetupWizardTest'`
-Expected: Kompilierfehler, `cannot find symbol ... consumeSetupWizardRequest`.
-
-- [ ] **Step 3: Den Wunsch in `ApplicationRuntimeLauncher` anlegen**
-
-Nach dem Feld `private static Kst4ContestApplication currentRuntime;` einfügen:
-
-```java
- /**
- * Whether the next runtime start shows the setup wizard although the profile is set up.
- * Set by the menu entry and cleared by the start that honours it.
- */
- private static final java.util.concurrent.atomic.AtomicBoolean SETUP_WIZARD_REQUESTED =
- new java.util.concurrent.atomic.AtomicBoolean(false);
-```
-
-Vor `public static boolean switchProfile(` einfügen:
-
-```java
- /** Asks the next runtime start to show the setup wizard. */
- static void requestSetupWizard() {
- SETUP_WIZARD_REQUESTED.set(true);
- }
-
- /**
- * Tells a starting runtime whether the wizard was asked for, and forgets the request.
- *
- * @return true exactly once per request
- */
- static boolean consumeSetupWizardRequest() {
- return SETUP_WIZARD_REQUESTED.getAndSet(false);
- }
-```
-
-- [ ] **Step 4: Run test to verify it passes**
-
-Run: `./gradlew :app-desktop:test --tests 'kst4contest.view.ApplicationRuntimeLauncherSetupWizardTest'`
-Expected: 1 Test, 0 Fehler.
-
-- [ ] **Step 5: Den Assistenten in `startRuntime` aufrufen**
-
-In `Kst4ContestApplication.java` die Importe ergänzen:
-
-```java
-import kst4contest.view.compose.wizard.SetupWizardLauncher;
-import kst4contest.view.compose.wizard.SetupWizardOutcome;
-```
-
-In `startRuntime` den Anfang ersetzen. Alt:
-
-```java
- if (!resolveOperatorProfileIfRequired()) {
- return;
- }
-
- ApplicationRuntimeLauncher.setCurrent(this);
-```
-
-Neu:
-
-```java
- if (!resolveOperatorProfileIfRequired()) {
- return;
- }
-
- /*
- * The setup wizard, before anything of this profile's runtime exists. It writes
- * preferences.xml and the ChatController built below reads it like any stored
- * setting, so there is no running session to bring up to date and no reload.
- * Blocks until the wizard is closed; see SetupWizardWindow for why that is safe on
- * either thread this method is called from.
- */
- SetupWizardOutcome setupWizardOutcome = SetupWizardLauncher.runIfNeeded(
- ActiveOperatorProfile.get().getPreferencesRelativeFileName(),
- ApplicationRuntimeLauncher.consumeSetupWizardRequest());
-
- ApplicationRuntimeLauncher.setCurrent(this);
-```
-
-Am Ende von `startRuntime`, unmittelbar vor dem Kommentar `Replaces Application.stop()` und dem `Runtime.getRuntime().addShutdownHook(`, einfügen:
-
-```java
- /*
- * "Save and connect" in the setup wizard. Here and not earlier: connecting needs the
- * runtime this method has just finished building. The same path as File -> Connect,
- * so a refused or failed connection is reported the way it is there.
- */
- if (setupWizardOutcome == SetupWizardOutcome.SAVED_AND_CONNECT) {
- uiDispatcher.runOnUi(this::menuActionConnect);
- }
-
-```
-
-Die Spec nennt hier `connectFromSettings`. `menuActionConnect` ruft dasselbe `chatcontroller.execute()` und zeigt einen Fehlschlag selbst an; `connectFromSettings` gibt nur einen Text zurück, den das Einstellungsfenster anzeigt, und das ist zu diesem Zeitpunkt nicht der Aufrufer.
-
-- [ ] **Step 6: Bauen und die berührten Tests laufen lassen**
-
-Run: `./gradlew :app-desktop:compileJava :app-desktop:test --tests 'kst4contest.view.*'`
-Expected: BUILD SUCCESSFUL; in `app-desktop/build/test-results/test/` kein `The running runtime is torn down first and the wizard shown afterwards, not the
- * other way round: a runtime shutting down flushes its pending layout write, and that
- * must not land on the file the wizard has just written.
- *
- * @return true if the new runtime was built
- */
- public static boolean rerunSetupWizard() {
- OperatorProfileSelection active = ActiveOperatorProfile.get();
-
- if (active == null) {
- return false;
- }
-
- requestSetupWizard();
- return switchProfile(active.getProfile());
- }
-```
-
-und die Importe ergänzen, soweit sie fehlen:
-
-```java
-import kst4contest.controller.ActiveOperatorProfile;
-import kst4contest.model.OperatorProfileSelection;
-```
-
-- [ ] **Step 6: Menüaktion in `Kst4ContestApplication`**
-
-Nach der Methode `menuActionToggleSettingsWindow()` einfügen:
-
-```java
- /**
- * Options -> setup assistant. Rebuilds the runtime of the active profile with the wizard
- * in front of it, which costs the running session; hence the question, and hence the
- * settings edits are settled first, as before a profile switch.
- */
- void menuActionOpenSetupWizard() {
- SettingsWindow.settleThen(() -> {
- boolean confirmed = ComposeAlert.confirm(
- kst4contest.view.i18n.CurrentStrings.get().getAlertSetupWizardTitle(),
- kst4contest.view.i18n.CurrentStrings.get().getAlertSetupWizardQuestion(),
- kst4contest.view.i18n.CurrentStrings.get().getAlertSetupWizardBody(),
- kst4contest.view.i18n.CurrentStrings.get().getDialogStartSetupWizard(),
- kst4contest.view.i18n.CurrentStrings.get().getDialogCancel(),
- chatcontroller.getChatPreferences().isGUI_darkModeActive());
-
- if (confirmed) {
- ApplicationRuntimeLauncher.rerunSetupWizard();
- }
- });
- }
-```
-
-- [ ] **Step 7: Run tests to verify they pass**
-
-Run: `./gradlew :app-desktop:test --tests 'kst4contest.view.compose.MainMenuModelTest' --tests 'kst4contest.view.compose.MainMenuRowScreenTest' --tests 'kst4contest.view.i18n.*'`
-Expected: alle grün.
-
-- [ ] **Step 8: Von Hand prüfen**
-
-1. `./gradlew :app-desktop:run`, mit dem eigenen Profil verbinden.
-2. Im Einstellungsfenster einen Wert ändern, **nicht** übernehmen. „Options → Setup assistant..." wählen.
-3. Erwartet: zuerst die Frage des Einstellungsfensters nach den offenen Änderungen; „Zurück" bricht alles ab, die Sitzung steht noch.
-4. Erneut wählen, Änderungen verwerfen. Erwartet: die Rückfrage „Sitzung beenden …". „Abbrechen" lässt die Sitzung stehen.
-5. Erneut, „Assistent starten". Erwartet: alle Fenster schließen, der Assistent erscheint, die Einstiegsseite bietet für Anmeldung und Station je „neu" und „unverändert".
-6. Beides „unverändert", bis zur Zusammenfassung, „Speichern". Erwartet: das Programm startet neu; Rufzeichen, Locator, Bänder, Fensteranordnung und alle Reiter wie vorher.
-7. `~/.praktiKST/preferences.xml` vor Schritt 5 kopieren und nach Schritt 6 vergleichen (`diff`). Erwartet: kein Unterschied in fachlichen Werten.
-
-Schritt 7 prüft die Annahme der Spec, dass die Laufzeit beim Abbau nicht über die Datei des Assistenten schreibt. Zeigt der Vergleich einen Verlust, das melden und nicht weitermachen.
-
-- [ ] **Step 9: Commit**
-
-```bash
-git add app-desktop/src/main/i18n/strings_en.properties app-desktop/src/main/i18n/strings_de.properties app-desktop/src/main/kotlin/kst4contest/view/compose/MainMenuBar.kt app-desktop/src/main/kotlin/kst4contest/view/compose/MainMenuModel.kt app-desktop/src/main/java/kst4contest/view/ComposeMenuActions.java app-desktop/src/main/java/kst4contest/view/ApplicationRuntimeLauncher.java app-desktop/src/main/java/kst4contest/view/Kst4ContestApplication.java app-desktop/src/test/kotlin/kst4contest/view/compose/MainMenuModelTest.kt app-desktop/src/test/kotlin/kst4contest/view/compose/MainMenuRowScreenTest.kt
-git commit -m "Reach the setup wizard from the Options menu"
-```
-
----
-
-### Task 8: Dokumentation und Abschluss
-
-**Files:**
-- Modify: `docs/PROJECT_CONTEXT.md` (Abschnitt „Important Decisions and Workarounds", ein Punkt am Ende der Liste)
-- Modify: `github_docs/de-Konfiguration.md`, `github_docs/en-Configuration.md` (neuer Abschnitt vor „Station Settings")
-- Modify: `app-desktop/src/main/i18n/strings_en.properties`, `strings_de.properties` (Schlüssel `profiles.createdWithoutCredentials`)
-- Delete: `docs/superpowers/plans/2026-11-18-einrichtungsassistent-stufe-1.md`
-
-**Interfaces:**
-- Consumes: das fertige Verhalten aus Task 1 bis 7.
-- Produces: nichts, worauf Code aufbaut.
-
-- [ ] **Step 1: Der Hinweis beim Anlegen eines Profils**
-
-Der Text schickt den Nutzer heute in den Reiter „Station". Nach dem Wechsel erscheint jetzt der Assistent.
-
-In `strings_de.properties` die Zeile `profiles.createdWithoutCredentials=…` ersetzen durch:
-
-```properties
-profiles.createdWithoutCredentials=Das Profil „{0}" wurde ohne Rufzeichen und Passwort angelegt. Nach dem Wechsel zu diesem Profil fragt der Einrichtungsassistent beides ab.
-```
-
-In `strings_en.properties` die Zeile mit demselben Schlüssel ersetzen durch:
-
-```properties
-profiles.createdWithoutCredentials=The profile "{0}" was created without callsign and password. After switching to it, the setup assistant asks for both.
-```
-
-Run: `grep -rn 'profilesCreatedWithoutCredentials\|createdWithoutCredentials' app-desktop/src/test`
-Jeden Test, der den alten Wortlaut festhält, auf den neuen ändern.
-
-- [ ] **Step 2: `docs/PROJECT_CONTEXT.md`**
-
-Am Ende der Liste unter „Important Decisions and Workarounds" anfügen:
-
-```markdown
-- **The setup wizard writes `preferences.xml` and does not touch a running session.** It runs
- in `startRuntime` after the profile is resolved and before the `ChatController` exists, on
- a `ChatPreferences` of its own, so what it stores is read like any stored setting. That is
- why it needs neither `SettingsDraft` nor the tab states: there is no session to bring up to
- date. From the menu the runtime is torn down first and the same profile restarted
- (`ApplicationRuntimeLauncher.rerunSetupWizard`), which costs the session and asks first. A
- profile counts as unconfigured when its callsign is empty or it still carries the bundled
- template's credentials (`LoginConfiguration`); there is no flag for it in the file. Stage 1
- asks for name, login, locator, bands and chat category; the reasons and the later stages
- are in `docs/superpowers/specs/2026-11-18-einrichtungsassistent-design.md`.
-```
-
-- [ ] **Step 3: Handbuch, deutsch**
-
-In `github_docs/de-Konfiguration.md` den ersten Absatz nach der Sprachzeile ersetzen. Alt:
-
-```markdown
-Nach dem ersten Start öffnet sich das **Einstellungsfenster** – dieses ist der zentrale Ausgangspunkt für alle Konfigurationen. Es empfiehlt sich, das Einstellungsfenster während des Betriebs geöffnet zu lassen (z. B. um den Beacon schnell ein- und auszuschalten).
-```
-
-Neu:
-
-```markdown
-Beim ersten Start fragt der **Einrichtungsassistent** das Nötigste ab (siehe unten). Danach öffnet sich das **Einstellungsfenster** – dieses ist der zentrale Ausgangspunkt für alle Konfigurationen. Es empfiehlt sich, das Einstellungsfenster während des Betriebs geöffnet zu lassen (z. B. um den Beacon schnell ein- und auszuschalten).
-```
-
-Unmittelbar vor `## Station Settings (Stationseinstellungen)` einfügen:
-
-```markdown
-## Einrichtungsassistent (ab v1.51)
-
-Solange ein Profil kein eigenes Rufzeichen hat, startet es mit dem Einrichtungsassistenten. Das gilt für die erste Installation und für jedes neu angelegte oder duplizierte Operator-Profil.
-
-Der Assistent fragt:
-
-1. **Persönliches** – Sprache und Anzeigename im Chat.
-2. **Anmeldung** – Rufzeichen und Passwort des ON4KST-Kontos.
-3. **Standort und Bänder** – Locator, aktive Bänder und Chatkategorie. Die Kategorie wird aus den Bändern vorgeschlagen und lässt sich ändern. Ein zweiter Chat ist freiwillig.
-4. **Zusammenfassung** – erst **Speichern** schreibt die Einstellungen. **Speichern und verbinden** meldet danach gleich am Chat an.
-
-Hat das Profil schon eine Station (etwa nach dem Duplizieren), fragt die erste Seite, ob sie **unverändert** bleiben oder **neu eingerichtet** werden soll. So braucht ein weiterer Operator an derselben Station nur Namen und Anmeldung einzutragen.
-
-**Später** schließt den Assistenten, ohne etwas zu schreiben. Er erscheint beim nächsten Start des Profils wieder, solange das Rufzeichen fehlt.
-
-Über **Options → Einrichtungsassistent...** lässt er sich jederzeit erneut aufrufen. Dabei wird die laufende Sitzung nach einer Rückfrage beendet und das Profil neu gestartet. Für einzelne Änderungen im Betrieb ist das Einstellungsfenster gedacht.
-
-Logprogramm, Rotor, AirScout und DX-Cluster-Server fragt der Assistent noch nicht ab; sie behalten ihre Werte und werden wie bisher im Einstellungsfenster eingestellt.
-
----
-
-```
-
-Die Versionsangabe „ab v1.51" gegen `gradle.properties` prüfen und auf die Version setzen, in der die Änderung erscheint. Kein Versionssprung in `gradle.properties` selbst.
-
-- [ ] **Step 4: Handbuch, englisch**
-
-In `github_docs/en-Configuration.md` den ersten Absatz ersetzen. Alt:
-
-```markdown
-After the first start, the **settings window** opens – this is the central starting point for all configuration. It is recommended to keep the settings window open during operation (e.g. to quickly toggle the beacon on and off).
-```
-
-Neu:
-
-```markdown
-On the first start, the **setup assistant** asks for the essentials (see below). After that the **settings window** opens – this is the central starting point for all configuration. It is recommended to keep the settings window open during operation (e.g. to quickly toggle the beacon on and off).
-```
-
-Unmittelbar vor `## Station Settings` einfügen:
-
-```markdown
-## Setup Assistant (since v1.51)
-
-As long as a profile has no callsign of its own, it starts with the setup assistant. This applies to the first installation and to every newly created or duplicated operator profile.
-
-The assistant asks for:
-
-1. **Personal** – language and the name shown in the chat.
-2. **Login** – callsign and password of the ON4KST account.
-3. **Location and bands** – locator, active bands and chat category. The category is suggested from the bands and can be changed. A second chat is optional.
-4. **Summary** – nothing is written until you click **Save**. **Save and connect** logs into the chat right afterwards.
-
-If the profile already has a station (after duplicating one, for example), the first page asks whether to leave it **unchanged** or to **set it up anew**. A further operator at the same station then only enters a name and a login.
-
-**Later** closes the assistant without writing anything. It appears again on the next start of the profile as long as the callsign is missing.
-
-**Options → Setup assistant...** opens it again at any time. This ends the running session after a confirmation and restarts the profile. Use the settings window for single changes during operation.
-
-The assistant does not ask about log program, rotator, AirScout and DX cluster server yet; they keep their values and are configured in the settings window as before.
-
----
-
-```
-
-- [ ] **Step 5: Der ganze Bau**
-
-Run: `./gradlew clean build`
-Expected: BUILD SUCCESSFUL.
-
-Danach, weil der Rückgabewert allein nichts beweist:
-
-```bash
-grep -l '