# 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 '