Files
Incido/tools/DESKTOP_FEASIBILITY.md
T
Incido Developer 7cc4eda90d feat(phase-1/m2.1): :core:backup — codecs + stream-based BackupBridge
Phase 1 M2 task 1 (tools/DESKTOP_PHASE_PLAN.md §4): extract the backup
bridge from :composeApp into a plain kotlin("jvm") module so the desktop
build can import/export the phone file format.

- git mv BackupCodec / EncryptedBackupCodec / EncryptedKeyCodec into
  core/backup, keeping the org.incido.compose.data.backup package so the
  Android diff is file moves + one dependency line (no import churn).
- New BackupBridge: the four BackupManager operations over
  InputStream/OutputStream instead of Uri (incl. the v0.3.3.3 preview
  hotfix catches); BackupPreview moves with it, same package.
- BackupManager stays in :composeApp as a thin Uri -> stream SAF shim,
  public API unchanged. Dedupe = task 3, desktop picker UI = task 2.

Verification passed: ./gradlew :core:backup:build :core:data-jvm:smoke
:spike:data-jvm:run + assembleDebug + :desktopApp:run --args="--data-dir
/tmp/incido-desktop-smoke --self-test --exit-after 6" — all green; run
output recorded in tools/DESKTOP_FEASIBILITY.md (Phase 1 status).
2026-10-05 18:51:07 +13:00

298 lines
16 KiB
Markdown

# Desktop feasibility spike (Phase 0) — findings
> The forward plan — remaining Phase-1 milestones, invariants and traps —
> lives in `tools/DESKTOP_PHASE_PLAN.md`, written as a cold-start handoff.
Branch `spike/desktop-feasibility`. Throwaway code lives in `spike/` and is
**not** wired into the Android build: `settings.gradle.kts` only gained two
`include()` lines and `gradle/libs.versions.toml` four entries. Nothing under
`app/`, `core/` or `composeApp/` was touched.
Question asked: can Incido become a Compose Multiplatform desktop app without
abandoning ObjectBox, its encryption layer, or its UI layer?
## Verdict
| # | Question | Verdict | Evidence |
|---|---|---|---|
| Q1 | Compose Multiplatform window builds + renders on KDE/Wayland | **PASS** | `:spike:compose-jvm:run` opened a window; `WINDOW-READY density=1.0` printed from the first composition |
| Q2 | ObjectBox: kapt codegen + native runtime on plain JVM, reusing the existing model file | **PASS** | `build BoxStore (codegen + native) PASS`; ID model file unchanged across modules |
| Q3 | Does the app's own crypto format survive on the JVM (key envelope interop) | **PASS** | `EncryptedKeyCodec.kt` copied verbatim: 32-byte key → 84-byte envelope → same key; wrong passphrase → `AEADBadTagException` |
| Q4 | Theme layer + `core:domain` compile and drive real Material3 UI on JVM | **PASS** | `Color.kt`/`Type.kt`/`NoteColors.kt` copied verbatim; only 2 Android-only lines removed from `Theme.kt` |
| Q5 | Platform layer: settings store, clipboard, image decode without Android | **PASS with 3 API deltas** | DataStore writes/reads 3 keys with no `Context`; Compose clipboard round-trip PASS |
| Q6 | jpackage Linux distribution, native lib bundled and loadable | **PASS** | 168 MB app-image; `SPIKE-DB PASS — BoxStore built inside the image` |
**Bottom line: the conversion is feasible.** No blocker found. Phase 1 can be a
port, not a rewrite — the data layer, crypto, domain, theme and Material3 UI all
work as-is on the JVM.
## Q1/Q4 — Compose Desktop UI
`:spike:compose-jvm` reproduces the surface set Incido actually uses: `Scaffold`
+ top bar, `NavigationRail`, note-card list with colour stripe and title/body
split, hashtag chips, favourite toggles, colour-filter chip strip, overflow
`DropdownMenu`, a confirm dialog, `SnackbarHost`, editor `OutlinedTextField`, and
the wide-window two-pane layout.
Run log (KDE Plasma, Wayland session, XWayland AWT):
```
AWT toolkit : sun.awt.X11.XToolkit
Skiko : Library resolved
WINDOW-READY density=1.0 notes=6 — first composition succeeded
clipboard : PASS (read back: incido-spike-clipboard)
```
No GL workarounds were needed (`-Dskiko.renderingApi=software` unused). Density
was 1.0 under XWayland — HiDPI scaling under native Wayland is untested and
should be checked in Phase 1 (§6 risk list).
Three real API deltas found while porting the UI, all mechanical:
1. `Dialog` is `androidx.compose.ui.window.Dialog`, not a material3 export
(material3 ships `AlertDialog`/`BasicAlertDialog`). Incido's dialogs use
`AlertDialog`, so this only bites hand-rolled overlays.
2. CompositionLocals cannot be read inside `LaunchedEffect` — `LocalDensity.current`
had to be captured at composition time. Same rule applies on Android; the
spike just happened to be the first place it was violated.
3. `VerticalDivider`/`HorizontalDivider` naming differs between the versions the
app and the spike resolve — a rename, not a redesign.
## Q2 — ObjectBox on the JVM
`spike/data-jvm` applies `org.jetbrains.kotlin.kapt`, points
`objectbox-plugin.json`-equivalent config at a **copy** of the app's
`objectbox-models/default.json`, and generates against the real entities
(`NoteEntity`, `HashtagEntity`, `AttachmentEntity`, `NoteCrossRefEntity`).
```
build BoxStore (codegen + native) PASS — native lib loaded
put NoteEntity (plaintext row) PASS — id=1
put NoteEntity (cipherVersion=1) PASS — id=2
blob round-trip integrity PASS — 4096 bytes identical
close + reopen same directory PASS — notes=2 hashtags=1
```
The generator printed **"ID model file unchanged"**, so generating in a second
module does not churn UIDs — the property that makes a shared-source Phase 1
(option B, sibling modules over a common `kotlin()` source set) safe. A desktop
build can open the same `.objectbox` file the Android app writes.
Gotchas recorded for Phase 1:
* Apply kapt with `apply(plugin = "org.jetbrains.kotlin.kapt")`; the
`alias(libs.plugins.kotlinKapt)` form fails with "already on classpath with
unknown version".
* kapt logs `W: Kapt currently doesn't support language version 2.0+` and falls
back to 1.9 for the generated code. Harmless, but expect it.
* The generator emits `MyObjectBox` into the **entity package**
(`org.incido.data.entity`), not `org.incido.data`.
* Resolved versions: `objectbox-java/kotlin/linux 4.0.3`, runtime reports
`4.0.2-2024-10-15`. `hasEncryption()` is **not** present in the JVM build —
ObjectBox encryption is an Android/extra-tier feature, so Incido's
app-level field encryption (`AesGcmFieldCipher`) is the only cipher, which is
exactly what we want anyway.
## Q3/Q5b — Crypto portability
`EncryptedKeyCodec.kt` was copied in **unmodified** (it imports only
`javax.crypto` + `java.security`) and exercised end-to-end:
```
recovery-key envelope (real codec) PASS — envelope=84 bytes, 32-byte key round-tripped
wrong passphrase is rejected PASS — rejected with AEADBadTagException
AES-256-GCM field cipher layout PASS — 4KB ok; 500 encrypts in 81 ms
PBKDF2 200k cost (per unlock) PASS — samples=[53, 56] ms per unlock on this CPU
```
Consequences for Phase 1:
* A recovery key exported from the phone opens encrypted notes on desktop with
**zero format changes** — same magic header, same PBKDF2 parameters, same
envelope. Backup/restore interop between platforms comes for free.
* `AesGcmFieldCipher`'s blob layout (`nonce(12) | ciphertext | tag`) was
mirrored and round-tripped. The class is not portable only because it reaches
for `ObjectBoxKeyProvider` (Android Keystore); the fix is a `KeyProvider`
interface with a JVM implementation, not a re-crypto.
* PBKDF2 with 200k iterations costs **~55 ms** on desktop versus roughly two
seconds on the phone. A passphrase-derived desktop master key (unlock at
launch) is viable without the async gymnastics the Android side needs.
* Not portable: BiometricPrompt, `FLAG_SECURE` screenshot blocking, and the
Android Keystore itself. Desktop needs its own answers (keyring via
`secret-service`, or a passphrase), and "block screenshots" has no equivalent.
## Q5a — Settings without a Context
```
data dir — would be /home/nick/.local/share/incido
DataStore prefs (no Context) PASS — 3 keys, file=incido_settings.preferences_pb (73 bytes)
```
API delta worth knowing before Phase 1: the multiplatform artifact
`androidx.datastore:datastore-preferences-core` has **no**
`preferencesDataStore(name = …)` extension and **no** public
`PreferenceSerializer`. The JVM entry point is
`PreferenceDataStoreFactory.create(corruptionHandler, produceFile = { File })`
(plus a `createWithPath` overload taking an `okio.Path`), and the corruption
handler lives in `androidx.datastore.core.handlers`. Keys and the
`.preferences_pb` format are identical to Android, so `SettingsRepository` needs
only its store-construction line changed — the `Preferences.Key` definitions and
all read/write logic port verbatim.
Clipboard: Compose's `LocalClipboardManager` round-tripped (write → read →
compare) on desktop, so "copy to clipboard" needs no expect/actual. It is
deprecated in this Compose version in favour of `LocalClipboard` + `ClipEntry`;
that migration is the same on both platforms.
Image decode: the spike decodes attachment bytes via
`org.jetbrains.skia.Image.makeFromEncoded(bytes).toComposeImageBitmap()` — the
desktop replacement for `BitmapFactory.decodeByteArray`. Compiling code path;
runtime decode only runs when `--image <file>` is passed.
## Q6 — Packaging
```
./gradlew :spike:compose-jvm:createDistributable → 168 MB app-image
SPIKE-DB PASS — BoxStore built inside the image, notes=0
```
`jpackage` built a self-contained Linux app-image (bundled jlink runtime) with no
extra host tooling — no FUSE, no `rpmbuild`, no Docker. `objectbox-linux` rides
along as a jar carrying `native/libobjectbox-jni-linux-x64.so` (2.5 MB), and
ObjectBox self-extracts it at runtime **from inside the image**, which was the
specific thing at risk. `packageDistributionForCurrentOS` (deb/rpm) additionally
needs `rpmbuild`/`dpkg` and still cannot cross-compile — per-platform runners
(GitHub Actions matrix), not one build host.
Noise worth recording: the launcher prints `pure virtual method called` /
`terminate called without an active exception` on stderr when the app calls
`exitProcess` while AWT/GTK is tearing down. Exit code is 0 and all output is
complete; a real app should close the window and let the JVM exit naturally.
## Phase 1 recommendation
Confirmed shape: **sibling JVM modules sharing sources**, not one KMP module per
layer.
1. `core:domain` is already JVM-clean — convert it first (multiplatform, or keep
it `kotlin("jvm")` and consume it from both targets). Zero code changes.
2. Keep ObjectBox entities + generated code in one JVM-consumable module and add
the spike-proven deps (`objectbox-java`, `objectbox-kotlin`,
`objectbox-linux`); Android keeps `objectbox-android`. The model file is the
shared contract — never regenerate UIDs.
3. Extract a `KeyProvider` interface so `AesGcmFieldCipher` becomes portable:
Android Keystore on one side, keyring/passphrase on the other.
4. Put `SettingsRepository`'s store construction behind an injected
`DataStore<Preferences>` factory (expect/actual if the code moves to common).
5. UI: budget ~15 files of real `android.*` coupling (context/resources,
`Build.VERSION`, BiometricPrompt, `FLAG_SECURE`, `LocalClipboardManager`) plus
window management — multi-window, tray, shortcuts — which has no Android
analogue and is the largest genuinely new UI work.
6. Compose Multiplatform 1.7.3 works but is behind. Decide in Phase 1 whether to
move the app to 1.8.x first; the spike proves feasibility on the pinned
version, not that 1.7.3 is the right target.
Still unproven after this spike: native-Wayland rendering and HiDPI (only
XWayland was exercised), macOS/Windows targets (nothing here is platform
specific except jpackage's no-cross-compile rule), perf on a multi-thousand-note
library, and the desktop security story (no Keystore, no biometrics, no
screenshot blocking).
## Re-running the spike
```bash
./gradlew :spike:data-jvm:run --args="/tmp/incido-spike-db" # S1 + S4 (Q2, Q3, Q5a/b)
./gradlew :spike:compose-jvm:run --args="--exit-after 6" # S2 (Q1, Q4, clipboard)
./gradlew :spike:compose-jvm:run --args="--image /path/x.png" # attachment decode
./gradlew :spike:compose-jvm:createDistributable # S5 (Q6)
spike/compose-jvm/build/compose/binaries/main/app/incido-spike/bin/incido-spike \
--probe-db --exit-after 4 # ObjectBox inside the image
```
`spike/` is meant to be deleted once Phase 1 lands; keep this file.
## Phase 1 status (same branch)
**M1a — platform-neutral data layer: DONE.** `:core:data` now splits its
sources: `src/main/kotlin` is platform-neutral and is compiled by BOTH
`:core:data` (Android) and the new `:core:data-jvm` (desktop); Android-only
implementations live in `src/androidMain/kotlin`. Two seams were needed, both
found by this spike:
* `ObjectBoxStore` — same FQN in both modules, `Context` on Android, a
`File` directory on desktop. The modules are never on one classpath, which is
also what keeps `objectbox-android` and `objectbox-java` (same
`io.objectbox.*` classes) from colliding.
* `ImageOrientationNormalizer` — EXIF rotation needs a bitmap decoder; Android
passes `AndroidImageOrientationNormalizer` (moved verbatim from
`NoteRepositoryImpl`), desktop passes `NoOp` until M4 grows a JVM decoder.
`./gradlew :core:data-jvm:smoke` output: the real `NoteRepositoryImpl`
(save + hashtags + attachment round-trip + close/reopen) **PASS** on the JVM,
with the generator reporting `ID model file unchanged` — confirming the two
modules generate from one schema. `assembleDebug` stays green.
Also fixed while here: `.gitignore` had `**/objectbox-models/`, which meant the
schema contract was **not in version control** — a fresh clone regenerated
UIDs. `default.json` is now tracked (everything else in that directory stays
ignored). This matters more now that two modules generate against it.
**M1b — desktop shell over the real repository: DONE.** New `:desktopApp`
(Compose Multiplatform, `compose.desktop` DSL, no explicit `application`
plugin — see the spike finding). `DesktopContainer` mirrors Android's
`AppContainer` construction order and owns its own library at
`$XDG_DATA_HOME/incido`; `--data-dir` opens any other library.
Verified headlessly (`--self-test` drives the same repository calls the "+"
button and the star make, `--exit-after` auto-closes):
```
library : /tmp/incido-desktop-smoke # written by :core:data-jvm:smoke
RENDER notes=0 selected=null # first frame (collectAsState initial)
RENDER notes=1 selected=1 # ObjectBox flow delivered
SELFTEST wrote note id=2 # write path through the UI's calls
RENDER notes=2 selected=2 # and it came back through the flow
--- reopen ---
RENDER notes=2 selected=2 # persisted
```
Two things that run proves beyond what the spike did: the desktop build reads a
library written by a *different* module's generated `MyObjectBox` (one schema,
two codegens), and ObjectBox's reactive flow feeds a Compose Desktop
composition. Note the first frame is always the empty initial value — anything
asserting on note counts must wait for the flow, not the first composition.
Still synthetic in this build: the theme (Material 3 defaults, not Incido's)
and the screens (this is a two-pane stand-in). Both are replaced by the M4
`composeApp` commonMain conversion. Not yet wired: settings, encryption (M3),
backups (M2), packaging (M5).
**M2 task 1 — extract `:core:backup`: DONE.** New plain-`kotlin("jvm")`
module holding `BackupCodec.kt`, `EncryptedBackupCodec.kt` and
`EncryptedKeyCodec.kt` (`git mv` — the Android diff is the three moves plus
one dependency line) and a new `BackupBridge`: the four `BackupManager`
operations re-expressed over `InputStream`/`OutputStream` instead of `Uri`.
The package name `org.incido.compose.data.backup` was kept on purpose, so no
consumer import changed; `BackupManager` stays in `:composeApp` as a thin
`Uri → stream` SAF shim with an identical public API (`BackupPreview` moved
to the bridge file, same package). Dedupe is task 3, desktop picker UI is
task 2 — deliberately not here.
Verification (all after the move, from a clean state):
```
./gradlew :core:backup:build BUILD SUCCESSFUL (serializers generated in the new module)
./gradlew assembleDebug BUILD SUCCESSFUL — Android unchanged
./gradlew :core:data-jvm:smoke RESULT: M1a PASS — the shared data layer runs on the JVM
./gradlew :desktopApp:run --args="--data-dir /tmp/incido-desktop-smoke --self-test --exit-after 6"
SELFTEST wrote note id=1 → RENDER notes=1 selected=1
./gradlew :spike:data-jvm:run … recovery-key envelope (real codec) PASS — 84-byte envelope,
32-byte key round-tripped; wrong passphrase → AEADBadTagException
```
Housekeeping found on the way: `:core:data-jvm:smoke` does not clear
`build/data-jvm-smoke/`, and the script asserts on a fresh library — a
second consecutive run fails with "expected 1 note, got 2". Run it against
a deleted directory (worth fixing in a later milestone).