This commit is contained in:
@@ -0,0 +1,158 @@
|
||||
# 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`](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`](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.
|
||||
|
||||
```sh
|
||||
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`.
|
||||
|
||||
```sh
|
||||
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`](docs/BUILD.md).
|
||||
|
||||
## Modules
|
||||
|
||||
```text
|
||||
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
|
||||
|
||||
```sh
|
||||
# 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:
|
||||
|
||||
```sh
|
||||
./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`](ios/README.md) before starting an iOS port.
|
||||
|
||||
## Start here for continued development
|
||||
|
||||
[`docs/ROADMAP.md`](docs/ROADMAP.md) defines the next slices and acceptance gates.
|
||||
[`docs/CODEX_HANDOFF.md`](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.
|
||||
Reference in New Issue
Block a user