fileworkbench/README.md

Fileworkbench — Android MVP source release 0.2.3

Open files, not accounts. A read-only, local-processing Android file browser and viewer, with a Kotlin Multiplatform document core that can be reused by a later native iOS shell.

Source release, not a verified APK. Host checks pass: 112 core/JVM and 16 listing checks. The complete project includes the SAF-D1 diagnostics and the earlier PDF and cursor-result corrections. The user's continuing folder failure is not diagnosed or claimed fixed. See docs/VALIDATION.md for executed host checks and Android-build limitations. No APK, JDK, Android SDK or iOS application is bundled.

0.2.3 — complete diagnostic project, Gradle 8.14.5 / JVM 17

No patch application is required. Extract this archive to a fresh directory and open the contained fileworkbench project. Do not copy old build scripts, .idea, .gradle, or gradle/gradle-daemon-jvm.properties over this release. Preserve your original checkout separately.

• Gradle 8.14.5 is pinned in the wrapper, bootstrap downloads and official SHA-256 checksums.
• Gradle daemon criteria, Java/Kotlin toolchains and JVM bytecode targets use 17. Install a JDK 17 locally and select it as the IDE Gradle JVM / JAVA_HOME; no absolute JDK path is shipped.
• Root plugin requests and catalog IDs remain distinct: the Kotlin JVM plugin is requested once at the root with apply false, then applied in its subproject.
• App version is 0.2.3 / code 5. The Locations footer shows Fileworkbench 0.2.3 · Browser diagnostics SAF-D1.
• A genuinely null directory-query cursor reports [SAF-D1/NULL_CURSOR], the provider authority, Android API and retained-read-grant status. No document URI/path or file content is included. This is evidence for the next diagnosis, not an automatic repair or broader storage grant.

See docs/RELEASE-0.2.3.md for the integrated changes and docs/BUILD.md for fresh-project setup.

What is in this release

• Native Browse / Recent screens; saved folder locations, nested navigation, breadcrumbs, filename search, folders-first sorting, size/date/type details, hidden-file toggle and opt-in provider thumbnails.
• Android files-app category and separate GET_CONTENT picker with MIME filters, single/multiple selection, confirmation, and temporary read-only copied results. It does not replace the system picker.
• Android system document/folder picker and Open with / single-file Share intent handling.
• Private bounded read-only snapshots, recent files, retained read grants where the provider permits them, explicit share-original / save-copy / preview-text export, details and cache/history cleanup.
• Native PDF page navigation and zoom, with a separate isolated PDF-rendering service and a bounded raw-pixel IPC transport. Raster image view with downsampling and zoom.
• Text/source, basic Markdown, CSV/TSV tables, and ZIP index views.
• Reading previews for DOCX, XLSX, PPTX, ODT, ODS and ODP: text, sheet values, simple document tables and slide sections. Search works on supported extracted text and archive names.
• Common Kotlin parsers, policy, models, search and export; JVM ZIP adapter; Apple framework targets.
• Unit/integration test sources, a local offline core test runner, Android smoke-test sources, a build/CI configuration, debug fixture DocumentsProvider, format matrix, threat model and implementation roadmap.

Office reading previews are not original-layout rendering. Images, charts, page geometry, advanced formatting and other content can be absent. The UI and text exports state this explicitly. No LibreOfficeKit, Collabora or third-party Office rendering binary is bundled. Legacy/macro-enabled Office, Office editing, PDF search/forms, and full-fidelity Office viewing are not implemented.

Use the browser

Choose Browse → Add folder once, grant access in Android's UI, and browse that folder inside Fileworkbench. Tap a file to preview; Back / Files returns to the same browser location. More → Open in another app hands off a read-only copy. Use Open file for single items elsewhere.

This uses folder-scoped access, not unrestricted storage access. Android 11+ does not permit bookmarking the storage root or Downloads root through this mechanism; individual Downloads files remain available through the system picker. There is no rename/delete/move feature in this release.

Read docs/BROWSER.md for registration semantics, picker security, storage restrictions, limits and the shared iOS-facing API. The browser's Android test plan is in docs/BROWSER_ACCEPTANCE.md.

Open the project

Gradle is pinned to 8.14.5. Use an installed JDK 17 for both your IDE Gradle JVM and terminal.

Use JDK 17 and an Android Studio version supporting AGP 8.11.1. Install Android SDK platform 36 and Build Tools 35.0.0. The Android app is configured for Android 8.0/API 26 and newer.

The source ZIP deliberately does not contain a downloaded Gradle wrapper JAR. The included launchers fetch the official Gradle 8.14.5 wrapper on first use and require its pinned SHA-256. The Gradle distribution is separately checksum-pinned. This is build-time networking only.

chmod +x gradlew scripts/*.sh
./gradlew --version
./gradlew :core:jvmTest :platform-jvm:test :androidApp:assembleDebug

On Windows use gradlew.bat; its bootstrap uses PowerShell. Before importing into Android Studio, run ./gradlew --version once (Windows: gradlew.bat --version) to materialize the wrapper JAR. Then open this root directory in Android Studio and select the androidApp run configuration.

After a successful Android build, the debug APK is expected at: androidApp/build/outputs/apk/debug/androidApp-debug.apk.

adb install -r androidApp/build/outputs/apk/debug/androidApp-debug.apk

This installs a development build, not a production-signed distribution. Full setup and troubleshooting: docs/BUILD.md.

Modules

androidApp/       Compose browser/viewer, SAF, file picker, copies, grants, PDF service, images
core/             commonMain: document core + browser models/filter/sort/MIME/selection budgets
platform-jvm/     bounded java.util.zip adapter, local-file preview orchestration
                      (shared by Android and JVM tests, NOT by iOS)
ios/              Apple integration plan; native framework targets live in core/build.gradle.kts
scripts/          verified Gradle bootstrap, offline tests, structural checks, Android build checks
docs/             architecture, build instructions, feature matrix, security, roadmap, validation
examples/         small ordinary text/CSV/source examples

Privacy defaults

There are no network, broad-storage or account permissions in the main manifest. The app never uploads documents or edits originals. It uses user-selected provider URIs, not all-files access. A selected external storage provider may itself use the network. Sharing/exporting/copying selected text are deliberate user actions outside the app's local-only boundary.

Snapshots, saved folder names/URIs, and recent filenames/URIs are stored privately in the app sandbox; there is no additional application-level encryption. Backup/transfer exclusions are configured. Cached data is not promised to be securely erased from flash storage. This MVP is not security-audited.

Verification commands

# With Gradle + Android SDK:
./scripts/verify-android.sh
# With a connected device/emulator:
./gradlew :androidApp:connectedDebugAndroidTest
# Without Android SDK or network, using an installed Kotlin compiler + Python 3:
./scripts/test-core.sh
python3 scripts/check-project.py
python3 scripts/test-folder-listing.py
./scripts/check-kotlin-syntax.sh

The offline runner uses the same test method bodies as the Gradle unit tests, stripping only runner annotations. It is not a substitute for an Android build or runtime test.

iOS path

On a compatible Mac/Xcode installation:

./gradlew -PenableIos=true :core:assembleFileworkbenchCoreReleaseXCFramework

This builds only the reusable framework. An Apple file-access/ZIP adapter and native UI still need implementation. Read ios/README.md before starting an iOS port.

Start here for continued development

docs/ROADMAP.md defines the next slices and acceptance gates. docs/CODEX_HANDOFF.md is a continuation brief for an implementation agent. Do not represent an interface, an unexecuted test, or a configured build target as completed runtime functionality. The immediate next gate is the first real Android build and device test.

Working name: Fileworkbench. Provisional application ID: dev.fileworkbench.android. New source is MIT-licensed; review distribution/licensing before adding third-party native engines.