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.input.key.type
import androidx.compose.ui.text.style.TextOverflow import androidx.compose.ui.text.style.TextOverflow
import androidx.compose.ui.unit.dp import androidx.compose.ui.unit.dp
import androidx.compose.ui.window.Tray
import androidx.compose.ui.window.Window import androidx.compose.ui.window.Window
import androidx.compose.ui.window.application import androidx.compose.ui.window.application
import androidx.compose.ui.window.rememberWindowState 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.edit
import androidx.datastore.preferences.core.intPreferencesKey import androidx.datastore.preferences.core.intPreferencesKey
import java.awt.GraphicsEnvironment
import java.io.File import java.io.File
import java.io.ByteArrayInputStream import java.io.ByteArrayInputStream
import java.io.FileOutputStream import java.io.FileOutputStream
@@ -121,6 +125,11 @@ fun main(args: Array<String>) {
val cryptoSelfTest = "--crypto-self-test" in args val cryptoSelfTest = "--crypto-self-test" in args
val cryptoReopen = "--crypto-reopen" in args val cryptoReopen = "--crypto-reopen" in args
val cryptoPassphrase = args.argAfter("--crypto-passphrase") ?: "selftest-passphrase" 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 // Recovery-envelope file legs: --key-export writes the INCKEY1 envelope
// the phone's Settings screen writes; --key-import reads one (e.g. a // the phone's Settings screen writes; --key-import reads one (e.g. a
// REAL phone export) with the passphrase and installs the key — the // 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("JVM : ${System.getProperty("java.vendor")} ${System.getProperty("java.version")}")
println("library : $dataDir") 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) val app = DesktopContainer(dataDir)
// M5.1: the desktop back stack. PlatformBackHandler (composeApp jvm // M5.1: the desktop back stack. PlatformBackHandler (composeApp jvm
@@ -149,16 +168,49 @@ fun main(args: Array<String>) {
?.coerceIn(640, 8_000) ?: 1100 ?.coerceIn(640, 8_000) ?: 1100
val savedHeight = windowPrefs[intPreferencesKey("window_height")] val savedHeight = windowPrefs[intPreferencesKey("window_height")]
?.coerceIn(480, 8_000) ?: 760 ?.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 { application {
val windowState = rememberWindowState( val windowState = rememberWindowState(
width = savedWidth.dp, width = savedWidth.dp,
height = savedHeight.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( Window(
onCloseRequest = ::exitApplication, onCloseRequest = ::exitApplication,
state = windowState, state = windowState,
title = "Incido", 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 // M5.1: Esc = system back. Consumed only when a handler is
// live; otherwise it falls through so popups keep their own // live; otherwise it falls through so popups keep their own
// Esc handling. This is the exact dispatcher --keys-smoke // Esc handling. This is the exact dispatcher --keys-smoke
@@ -184,6 +236,9 @@ fun main(args: Array<String>) {
settingsSmoke = settingsSmoke, settingsSmoke = settingsSmoke,
editorSmoke = editorSmoke, editorSmoke = editorSmoke,
keysSmoke = keysSmoke, keysSmoke = keysSmoke,
showFirstRun = !onboarded && !otherScriptedLeg,
onboardingSmoke = onboardingSmoke,
onboardingVerify = onboardingVerify,
backupImport = backupImport, backupImport = backupImport,
backupExport = backupExport, backupExport = backupExport,
backupExportEnc = backupExportEnc, backupExportEnc = backupExportEnc,
@@ -214,6 +269,9 @@ private fun NotesWindow(
settingsSmoke: Boolean, settingsSmoke: Boolean,
editorSmoke: Boolean, editorSmoke: Boolean,
keysSmoke: Boolean, keysSmoke: Boolean,
showFirstRun: Boolean,
onboardingSmoke: Boolean,
onboardingVerify: Boolean,
backupImport: String?, backupImport: String?,
backupExport: String?, backupExport: String?,
backupExportEnc: String?, backupExportEnc: String?,
@@ -230,6 +288,41 @@ private fun NotesWindow(
// M4.5: the real settings screen replaces the M1b placeholder list. // M4.5: the real settings screen replaces the M1b placeholder list.
var showSettings by remember { mutableStateOf(false) } 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 // M3: theme_mode is a real shared setting here — resolveDark picks the
// scheme. M4.5b: the app's OWN IncidoTheme wraps the shell — the // scheme. M4.5b: the app's OWN IncidoTheme wraps the shell — the
// shared screens get the exact color scheme + typography the phone // 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) { LaunchedEffect(notes.size) {
// Logged on every change: proves the ObjectBox subscription actually // Logged on every change: proves the ObjectBox subscription actually
// delivers to the composition (the first frame is always the empty // 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. **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: # 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-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) ./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 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 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, bogus FAIL lines and a corrupt-on-paper result. Sequential, separate processes,
fresh dir first. 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) ## 4. M2 — the backup bridge (next up; the product's reason to exist)