fileworkbench/docs/HOTFIX-0.2.2.md

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:

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:

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