initial commit v 0.2.0

docs/HOTFIX-0.2.2.md

@@ -0,0 +1,61 @@
+# 0.2.2 — Valid folder listings incorrectly treated as missing
+
+## Runtime correction
+
+File: `androidApp/src/main/kotlin/dev/fileworkbench/android/browser/SafBrowserStore.kt`.
+
+Before, the no-listing check followed the complete resource-handling expression:
+
+```kotlin
+resolver.query(children, PROJECTION, null, null, null, signal)?.use { cursor ->
+    // Read rows and optional status messages.
+    cursor.extras.getString(DocumentsContract.EXTRA_ERROR)?.let { information = safeFileLabel(it) }
+} ?: throw PreviewException("The storage provider did not return a folder listing.")
+```
+
+The last expression returns null when no error is reported, and `use` returns the
+result of its block. Thus success triggered the no-listing error. This was a
+Fileworkbench control-flow bug, not a requirement for broader storage access.
+
+After, check only the cursor returned by the provider:
+
+```kotlin
+val queryResult = resolver.query(children, PROJECTION, null, null, null, signal)
+    ?: throw PreviewException("The storage provider did not return a folder listing.")
+queryResult.use { cursor ->
+    // The existing row/extras handling stays unchanged.
+}
+```
+
+A genuinely null query result still fails; an empty cursor is a valid empty listing.
+The change does not swallow exceptions or treat missing access as an empty folder.
+
+## Apply without replacing local build configuration
+
+Use either the supplied replacement `SafBrowserStore.kt` at the path above or
+`git apply` with the supplied one-file patch. Do not apply both. The patch was
+verified against the shipped 0.2.0 and 0.2.1 source, whose browser file is identical.
+It changes no Gradle/JDK settings, dependencies, manifest permissions, stored data,
+or document contents. Applying only the patch does not change the displayed
+application version. The complete source release sets version 0.2.2 / code 4.
+
+Rebuild and install over the old debug app, then open/refresh the saved folder.
+There is no migration and no reason to clear app data for this fix. Temporary grants
+may require selecting a folder again; no new broad permission is requested.
+
+## Regression coverage
+
+`scripts/test-folder-listing.py` extracts the actual cursor-reading block and runs
+14 JVM checks on test doubles. The old source fails 9 of these with the reported
+message; the corrected source passes all 14. This is not an Android API/device test.
+The debug fixture and `BrowserIntegrationTest` add five real Android test cases;
+those still need a connected device/emulator to execute. The existing normal,
+nested and large-folder tests also cover the corrected path.
+
+See `VALIDATION.md` for the executed checks and their exact limitations.
+
+## Primary references
+
+- Kotlin use returns the block result: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.io/use.html
+- Android EXTRA_ERROR is optional: https://developer.android.com/reference/android/provider/DocumentsContract#EXTRA_ERROR
+- ContentResolver query result: https://developer.android.com/reference/android/content/ContentResolver