feat(phase-1/m5.2): tray + single-instance lock + first-run onboarding

SingleInstanceLock (OS FileLock on <dataDir>/incido.lock) claims the library
before the container starts; a second launch prints INSTANCE and exits 0 —
which also converts the wedged-child trap into a clean message. Tray
(ApplicationScope extension; Item/Separator menu) attaches only for
non-scripted, non-headless, SystemTray-capable sessions; close=quit kept.
First-run dialog explains the per-machine library + backup bridge, gated on
onboarded_v1 in the window store. Two new §3 traps recorded (Window
iconBitmap overload ambiguity; Tray receiver/params) + new harness legs in §1.

Verify: second launch same dir (INSTANCE ... exits, 0); interactive run
(TRAY attached, live KDE SNI); :desktopApp:run --args="--data-dir
/tmp/incido-m52-ob --onboarding-smoke --exit-after 8" (shown=true,
flag-persisted=true PASS) then --onboarding-verify (shown=false gate
respected); --keys-smoke KEYS ALL-OK; --self-test id=1;
:core:data-jvm:smoke M1a PASS; assembleDebug SUCCESSFUL.
This commit is contained in:
Incido Developer committed 2026-10-06 22:54:48 +13:00
1 parent 639f39d187
commit 0cad7729aa
7 files changed
+255

No files matched your search

@@ -49,11 +49,15 @@ import androidx.compose.ui.input.key.key
import androidx.compose.ui.input.key.type
import androidx.compose.ui.text.style.TextOverflow
import androidx.compose.ui.unit.dp
import androidx.compose.ui.window.Tray
import androidx.compose.ui.window.Window
import androidx.compose.ui.window.application
import androidx.compose.ui.window.rememberWindowState
import androidx.compose.ui.res.painterResource
import androidx.datastore.preferences.core.booleanPreferencesKey
import androidx.datastore.preferences.core.edit
import androidx.datastore.preferences.core.intPreferencesKey
import java.awt.GraphicsEnvironment
import java.io.File
import java.io.ByteArrayInputStream
import java.io.FileOutputStream
@@ -121,6 +125,11 @@ fun main(args: Array<String>) {
val cryptoSelfTest = "--crypto-self-test" in args
val cryptoReopen = "--crypto-reopen" in args
val cryptoPassphrase = args.argAfter("--crypto-passphrase") ?: "selftest-passphrase"
// M5.2 scripted onboarding legs: --onboarding-smoke on a FRESH dir
// asserts the dialog shows and its dismiss persists the flag;
// --onboarding-verify on the SAME dir asserts the flag gates it off.
val onboardingSmoke = "--onboarding-smoke" in args
val onboardingVerify = "--onboarding-verify" in args
// Recovery-envelope file legs: --key-export writes the INCKEY1 envelope
// the phone's Settings screen writes; --key-import reads one (e.g. a
// REAL phone export) with the passphrase and installs the key — the
@@ -132,6 +141,16 @@ fun main(args: Array<String>) {
println("JVM : ${System.getProperty("java.vendor")} ${System.getProperty("java.version")}")
println("library : $dataDir")
// M5.2: single-instance claim BEFORE the container opens the library.
// The §3 trap (a wedged AWT child still holding ObjectBox's
// single-writer lock) surfaces here as a clean message instead of a
// half-initialized crash — the OS FileLock dies with its process.
val instanceHandle = SingleInstanceLock(dataDir).tryAcquire()
if (instanceHandle == null) {
println("INSTANCE another Incido already owns $dataDir — this copy exits")
return
}
val app = DesktopContainer(dataDir)
// M5.1: the desktop back stack. PlatformBackHandler (composeApp jvm
@@ -149,16 +168,49 @@ fun main(args: Array<String>) {
?.coerceIn(640, 8_000) ?: 1100
val savedHeight = windowPrefs[intPreferencesKey("window_height")]
?.coerceIn(480, 8_000) ?: 760
// M5.2: first-run state lives in the desktop-only window store (same
// rule as geometry — settings keeps the phone-shared schema).
val onboarded = windowPrefs[booleanPreferencesKey("onboarded_v1")] == true
// Other scripted legs suppress tray chrome AND the first-run overlay —
// their assertions ride the bare shell. --onboarding-* legs are the
// exception: they exercise the overlay's own gate (fresh vs onboarded).
val otherScriptedLeg = selfTest || settingsSmoke || editorSmoke || keysSmoke ||
cryptoSelfTest || cryptoReopen ||
backupImport != null || backupExport != null || backupExportEnc != null ||
keyExport != null || keyImport != null
val attachTray = !(otherScriptedLeg || onboardingSmoke || onboardingVerify) &&
!GraphicsEnvironment.isHeadless() && java.awt.SystemTray.isSupported()
application {
val windowState = rememberWindowState(
width = savedWidth.dp,
height = savedHeight.dp,
)
// M5.2: tray (ApplicationScope receiver — sibling of Window, not
// inside its content). Closing the window still QUITS (no
// hide-to-tray): exitApplication semantics stay, and every
// harness leg keeps its teardown; the tray restores from
// minimized and offers a quick Quit.
if (attachTray) {
Tray(
icon = painterResource("tray_icon.png"),
tooltip = "Incido",
menu = {
Item("Show Incido") { windowState.isMinimized = false }
Separator()
Item("Quit Incido") { exitApplication() }
},
)
LaunchedEffect(Unit) { println("TRAY attached") }
}
Window(
onCloseRequest = ::exitApplication,
state = windowState,
title = "Incido",
// NOTE: the 1.7.3 Window overloads go ambiguous if the
// iconBitmap arg is added here — window/taskbar icon comes
// from the jpackage distribution icon instead (M5.3), and
// app_icon_32.png ships for that purpose.
// M5.1: Esc = system back. Consumed only when a handler is
// live; otherwise it falls through so popups keep their own
// Esc handling. This is the exact dispatcher --keys-smoke
@@ -184,6 +236,9 @@ fun main(args: Array<String>) {
settingsSmoke = settingsSmoke,
editorSmoke = editorSmoke,
keysSmoke = keysSmoke,
showFirstRun = !onboarded && !otherScriptedLeg,
onboardingSmoke = onboardingSmoke,
onboardingVerify = onboardingVerify,
backupImport = backupImport,
backupExport = backupExport,
backupExportEnc = backupExportEnc,
@@ -214,6 +269,9 @@ private fun NotesWindow(
settingsSmoke: Boolean,
editorSmoke: Boolean,
keysSmoke: Boolean,
showFirstRun: Boolean,
onboardingSmoke: Boolean,
onboardingVerify: Boolean,
backupImport: String?,
backupExport: String?,
backupExportEnc: String?,
@@ -230,6 +288,41 @@ private fun NotesWindow(
// M4.5: the real settings screen replaces the M1b placeholder list.
var showSettings by remember { mutableStateOf(false) }
// M5.2: first-run onboarding state. dismissWelcome is the EXACT
// callback the dialog's buttons call, so the smoke leg asserting
// through it asserts the real path.
var showWelcome by remember { mutableStateOf(showFirstRun) }
val uiScope = rememberCoroutineScope()
fun dismissWelcome(openSettings: Boolean) {
showWelcome = false
uiScope.launch {
windowStore.edit { it[booleanPreferencesKey("onboarded_v1")] = true }
}
if (openSettings) showSettings = true
}
if (onboardingSmoke) {
LaunchedEffect(Unit) {
delay(1500)
val shownFresh = showWelcome
println("ONBOARD fresh-run shown=$shownFresh ${if (shownFresh) "PASS" else "FAIL"}")
if (shownFresh) {
dismissWelcome(false)
delay(800)
val flag = windowStore.data.first()[booleanPreferencesKey("onboarded_v1")] == true
println("ONBOARD flag-persisted=$flag ${if (flag) "PASS" else "FAIL"}")
}
}
}
if (onboardingVerify) {
LaunchedEffect(Unit) {
delay(1500)
println(
"ONBOARD reopened shown=$showWelcome " +
(if (!showWelcome) "PASS (gate respected)" else "FAIL (flag ignored!)"),
)
}
}
// M3: theme_mode is a real shared setting here — resolveDark picks the
// scheme. M4.5b: the app's OWN IncidoTheme wraps the shell — the
// shared screens get the exact color scheme + typography the phone
@@ -251,6 +344,15 @@ private fun NotesWindow(
)
}
// M5.2: first-run overlay, above whichever screen the shell renders.
if (showWelcome) {
FirstRunDialog(
dataDirPath = app.dataDir.absolutePath,
onStartWriting = { dismissWelcome(false) },
onImportFromPhone = { dismissWelcome(true) },
)
}
LaunchedEffect(notes.size) {
// Logged on every change: proves the ObjectBox subscription actually
// delivers to the composition (the first frame is always the empty
@@ -0,0 +1,57 @@
package org.incido.desktop
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.padding
import androidx.compose.material3.Card
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Text
import androidx.compose.material3.TextButton
import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp
import androidx.compose.ui.window.Dialog
/**
* M5.2 — first-run onboarding.
*
* Says the one thing a new desktop user must not guess (Development
* Plan §6 product decision): this library lives on THIS machine, and the
* encrypted backup file is the only bridge to the phone. Never shown
* once the `onboarded_v1` window-store flag is set, never shown for
* scripted smoke legs.
*
* `Dialog` here is `androidx.compose.ui.window.Dialog` — the §3 trap:
* material3 ships AlertDialog, not Dialog.
*/
@Composable
fun FirstRunDialog(
dataDirPath: String,
onStartWriting: () -> Unit,
onImportFromPhone: () -> Unit,
) {
Dialog(onDismissRequest = onStartWriting) {
Card(Modifier.fillMaxWidth()) {
Column(Modifier.padding(24.dp), verticalArrangement = Arrangement.spacedBy(12.dp)) {
Text("Welcome to Incido", style = MaterialTheme.typography.headlineSmall)
Text(
"Your notes library lives on this machine, in\n" +
"$dataDirPath\n" +
"It stays private and offline. The only bridge to your " +
"phone is the encrypted backup file you create in " +
"Settings \u25B8 Backup \u2014 export there, import here.",
style = MaterialTheme.typography.bodyMedium,
)
Row(
Modifier.fillMaxWidth(),
horizontalArrangement = Arrangement.End,
) {
TextButton(onClick = onImportFromPhone) { Text("Import from phone backup") }
TextButton(onClick = onStartWriting) { Text("Start writing") }
}
}
}
}
}
@@ -0,0 +1,38 @@
package org.incido.desktop
import java.io.File
import java.nio.channels.FileChannel
import java.nio.file.StandardOpenOption
/**
* M5.2 — per-library single-instance guard.
*
* ObjectBox's single-writer lock and DataStore's file lock are crash
* recovery, not coexistence: a second launch against the same data dir
* would wedge on them (or worse, interleave writes). An OS `FileLock`
* dies with its process — even on `kill -9` — so it needs no stale-file
* cleanup, unlike a pid file.
*/
class SingleInstanceLock(private val dataDir: File) {
/**
* Non-blocking claim. Returns the handle to keep for the process
* lifetime, or null when another live process owns [dataDir].
*/
fun tryAcquire(): AutoCloseable? {
val channel = FileChannel.open(
File(dataDir, "incido.lock").toPath(),
StandardOpenOption.CREATE,
StandardOpenOption.WRITE,
)
val lock = runCatching { channel.tryLock() }.getOrNull()
if (lock == null) {
channel.close()
return null
}
return AutoCloseable {
runCatching { lock.release() }
runCatching { channel.close() }
}
}
}
Binary file not shown.

After

Width:  |  Height:  |  Size: 2.4 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 2.4 KiB

+43
View File
@@ -853,6 +853,49 @@ M5.1 suite:
**Next up: M5.2** — tray + single-instance + first-run onboarding.
**M5.2 — tray + single-instance + first-run onboarding: DONE.**
- **Single instance:** `SingleInstanceLock` claims an OS `FileLock` on
`<dataDir>/incido.lock` BEFORE the container opens the library. A
second launch prints `INSTANCE another Incido already owns …` and
exits 0. Bonus: this converts the §3 "wedged AWT child holds the
ObjectBox lock" trap into that same clean message. OS locks die with
the process, so `kill -9` needs no cleanup — a pid file would.
- **Tray:** `Tray` sits directly in `application {}` (it is an
*ApplicationScope* extension, NOT callable from window content — and
its params are icon/state/tooltip/menu only, no onClick; menu items
are capitalized `Item(…)`/`Separator()`). Show = unminimize, Quit =
exitApplication. Closing the window still quits (no hide-to-tray —
keeps exit semantics and every harness leg). Guarded
`!headless && SystemTray.isSupported()`; scripted legs never attach.
`TRAY attached` proven live under KDE.
- **Onboarding:** first-run dialog (window.Dialog per the §3 trap) says
where the library lives and that the backup file is the phone bridge.
Gate = `onboarded_v1` flag in the desktop-only window store; dismiss
writes it; scripted legs skip it. `--onboarding-smoke` (fresh dir:
shown + flag persisted) and `--onboarding-verify` (same dir: not
shown) close both directions.
- **New §3 trap paid:** Compose 1.7.3 `Window` goes AMBIGUOUS between
its two overloads when the `iconBitmap` arg is passed ("cannot infer
type" on an unrelated lambda param). Window/taskbar icon therefore
comes from the distribution icon (M5.3).
```
M5.2 suite:
second launch, same dir INSTANCE … this copy exits (exit 0)
:desktopApp:run (interactive-style) TRAY attached (live KDE SNI)
:desktopApp:run … --onboarding-smoke shown=true PASS, flag-persisted=true PASS
:desktopApp:run … --onboarding-verify shown=false PASS (gate respected)
:desktopApp:run … --keys-smoke KEYS ALL-OK (regression)
:desktopApp:run … --self-test SELFTEST id=1
:core:data-jvm:smoke RESULT: M1a PASS
assembleDebug BUILD SUCCESSFUL
```
**Next up: M5.3** — packaging: version wired to versionName, icons,
`.desktop` entry, createDistributable re-verify + size, Wayland/HiDPI
verdict.
+15
View File
@@ -51,6 +51,12 @@ Commands that must stay green:
# after leg A (it proves the relaunch), against the same fresh data dir:
./gradlew :desktopApp:run --args="--data-dir /tmp/incido-desktop-crypto --crypto-self-test --crypto-passphrase m3-script-pw --exit-after 20" # leg A (leaves lib encrypted)
./gradlew :desktopApp:run --args="--data-dir /tmp/incido-desktop-crypto --crypto-reopen --exit-after 15" # leg B (verifies + decrypts back)
# M5.1/M5.2 keyboard + onboarding legs. Onboarding legs are SEQUENTIAL
# against the same fresh dir (smoke writes the onboarded flag, verify
# asserts the gate):
./gradlew :desktopApp:run --args="--data-dir /tmp/incido-desktop-keys --keys-smoke --exit-after 12"
./gradlew :desktopApp:run --args="--data-dir /tmp/incido-desktop-ob --onboarding-smoke --exit-after 8" # fresh dir: shown + flag
./gradlew :desktopApp:run --args="--data-dir /tmp/incido-desktop-ob --onboarding-verify --exit-after 6" # same dir: stays hidden
```
Versions that matter: Compose Multiplatform `1.7.3`, AndroidX Compose BOM
@@ -107,6 +113,15 @@ app version `0.4.2.0` (code 38).
command group — leg B opening the library leg A is still writing produces
bogus FAIL lines and a corrupt-on-paper result. Sequential, separate processes,
fresh dir first.
* Compose 1.7.3 `Window`: passing the `iconBitmap` arg makes the two overloads
ambiguous — the error surfaces as "cannot infer type" on an UNRELATED lambda
parameter. Leave it out; the distribution icon (jpackage) owns the taskbar.
* `Tray` (1.7.3) is an `ApplicationScope` extension — call it in `application {}`
next to `Window`, not inside window content. Params: icon/state/tooltip/menu
(no onClick); menu members are capitalized `Item`/`Separator`/`CheckboxItem`.
* KWin under Wayland drops xdotool XTEST keys aimed at the XWayland window even
when focus probes show it focused — desktop key handling can't be injected
headless here; verify real keypresses by hand.
## 4. M2 — the backup bridge (next up; the product's reason to exist)