SoftwareApp
b1bc805af0
Everything this repository promised was voluntary until now: 371 tests, lint and the generated code map ran only if whoever changed the code remembered to run them. tools/verify.sh is that gate as one command - the map check, detekt, the unit tests and lint, cheapest first so a stale document fails in a second rather than after a release build - and --release adds the R8 build. The ordering is not cosmetic: the two cheapest checks are also the two that catch drift nothing else can see. The same script runs in three places: CI on every push and pull request, a nightly --release job (R8 is the one check nothing else performs, and it has hidden a real defect here once), and a pre-push hook once the clone has been told to use .githooks. The nightly also uploads the R8 mapping, which is what turns a release stack trace back into a line of Kotlin and is only worth keeping if it belongs to the build that shipped. Detekt is adopted with a baseline, which is the entire adoption strategy: everything it finds today is frozen in config/detekt/baseline.xml, so the gate fails on a new finding rather than on a backlog nobody is going to clear this week. Entries are keyed by rule, file and enclosing declaration, so a new long function is still reported inside a file that already has one - proved by writing a TODO into a file, watching the build fail on that exact line, and taking it out again. What it found first agrees with the churn numbers from the last pass: ArchiveEngine 16 findings, BrowserViewModel 11, SelectionBar 9, 86 in total over 13 rules, the largest groups being the complexity ones this was added for (cyclomatic complexity 10, nested block depth 7, too many functions 4, long methods 3, two classes over 700 lines) plus 30 over-long lines. Three findings were fixed rather than parked, because they were real: dead `menuOpen` state left in BrowserScreen when the overflow menu moved into BrowserTopBar, a missing trailing newline, and two `db` parameters that are the platform's signature rather than an oversight (suppressed with that reason written next to them). Four rules were configured rather than obeyed: PackageNaming, because the applicationId's underscore is an identity this app cannot change; FunctionNaming, for @Composable (PascalCase by convention) and for backticked test names, which is the project's specification style; MagicNumber, because sizes and limits are named constants here; and MatchingDeclarationName, because a file is named after its concept rather than after a declaration inside it. Two tooling facts cost real time and are in neither tool's documentation. Detekt runs through its CLI rather than its Gradle plugin: the plugin performs the analysis inside the build's own JVM, and detekt 1.23 cannot parse JDK 25's version string - it fails with "25.0.4.1" as the entire error message - so the task drives detekt-cli on a 21 launcher, which is also the only way to pin the JVM the analyser runs on. And a baseline has to exist before it can be read, which is why it starts as an empty document rather than being generated into place. Verified: the fast gate is green in 17 seconds, --release adds a 36-second R8 build, 371 JVM tests still pass, lint is clean and the map is current. CHANGELOG, README, AGENTS.md, ROADMAP (the gate is now a recorded decision) and the regenerated map carry it.
15 KiB
15 KiB
Roadmap
File Manager is built against a fixed milestone plan (M0–M15). This file is the single source of truth for what is done and what remains.
Legend: ✅ done · 🚧 in progress · ⏳ not started · 💡 candidate (proposed, not scheduled)
Milestones
| # | Milestone | Status | Evidence / notes |
|---|---|---|---|
| M0 | Toolchain & scaffold | ✅ | Gradle 9.3.1 + AGP 9.1.0 wrapper, version catalog, app module, Compose theme, debug APK builds, installs and runs on the phone AVD: package de.softwareapp_hb.filemanager.debug, versionCode 1, minSdk 26/targetSdk 36, no INTERNET permission, lintDebug clean (one expected UnusedResources for the not-yet-used notification icon) |
| M1 | Pure-Kotlin core + JVM tests | ✅ | core/ is Android-free: StoragePath (normalised absolute paths that cannot escape the root), FileEntry + FileKind classification, MimeTypes, NaturalOrder + SortSpec (directories first; file2 before file10), FileSize, NameMatcher (substring + */? glob), NameAllocator ("name (1)") and TransferPlanner (conflict policies, move-into-self). 44 JVM tests across 10 classes, all green |
| M2 | Storage layer | ✅ | StorageSource with two backends — AllFilesSource (java.io.File under all-files access) and SafSource (DocumentsContract over a persisted tree URI), the latter split so the tree↔path mapping (SafDocumentIds) is exhaustively testable; SafGrant for the picker and its persistence; VolumeRepository (StorageManager/StorageVolume + StatFs); StorageAccess + StorageAccessPolicy for the all-files/SAF decision. 76 JVM tests total (32 added here) |
| M3 | Operations engine + service | ✅ | domain/FileOperations composes the backend primitives into copy/move/delete/rename with recursive walking, an honest progress total, cooperative cancellation between entries and per-item failure reporting; conflicts are decided through the M1 TransferPlanner (ASK is surfaced for the UI to resolve). service/FileOpService is a dataSync foreground service mirroring progress into a notification (FileOpNotifications + text/TextRes). 99 JVM tests total (23 added here) |
| M4 | Compose UI | ✅ | BrowserViewModel + BrowserUiState over StorageLocation; browser screen with list/grid, breadcrumbs, in-folder search, a sort/hidden-files/view sheet, multi-select action bar, details sheet, and new-folder/rename/delete/conflict dialogs; a roots view and the "All files access" + SAF-folder prompts; data/MediaStoreDeleter routes a delete through the platform's own dialog where it can and falls back to a direct delete; a FileProvider backs "open with" and share. 115 JVM tests total (16 added here) |
| M5 | Analysis, archives, viewers | ✅ | domain/UsageAnalysis measures recursive folder sizes and finds the largest files, shown by a bar-per-row storage-usage screen; domain/ArchiveEngine creates ZIP and extracts ZIP/TAR/TAR.GZ/GZ/BZ2/XZ/7z using java.util.zip + Commons Compress + XZ for Java (no native code), with every entry name filtered through core/ArchivePath against zip-slip; a Coil-backed image viewer, thumbnails in the list and grid, a text editor, and compress/extract in the selection bar. 141 JVM tests total (26 added here) |
| M6 | Release config & Play readiness | ✅ | Upload keystore generated (4096-bit RSA, CN=Hadrian Burkhardt) and wired through the git-ignored keystore.properties; bundleRelease + assembleRelease verified — 4 682 814-byte .aab (sha256 9014627a…), 2 081 955-byte APK signed by the upload key, R8 mapping kept. PLAY_RELEASE_CHECKLIST (incl. the Permissions Declaration Form for "All files access", the Data safety answers and the shipped-permission audit) and PRIVACY.md written for a restricted-permission app. Shipped permission set audited: no INTERNET |
| M7 | On-device validation & hardening | ✅ | Run on a real Xiaomi M2101K7AG (Android 12 / MIUI V140) — see EDGE_CASE_TESTING. Verified on hardware: the first-run permission prompt, granting "All files access" while the app is alive (picked up on resume), browsing real storage, the text editor's read and write path (independently checked with adb shell cat), the storage-usage screen, landscape layout, and graceful degradation when access is revoked mid-use. Found and fixed two real defects: misleading first-run copy ("Full access was declined" on a device where nothing had been declined), and a usage screen that stayed blank for ~45–60 s on a 55 GB volume — now one listing per directory instead of a stat per node, with rows streamed out as they are measured. 142 JVM tests |
| M8 | Localisation groundwork | ✅ | Every user-visible string is in res/values/strings.xml with real <plurals>, and text/TextRes.kt maps both OperationKind and FileKind onto resources so the screen, the notification and the details sheet cannot drift. The audit found a genuine miss: the details sheet rendered FileKind.name, i.e. untranslatable English — now a resource. isPseudoLocalesEnabled = true on the debug build makes "did every string come from resources?" mechanically checkable; verified en-rXA is present in the debug APK and the flag is debug-only. Byte units and the timestamp pattern are deliberately unlocalised, and the README says why. 142 JVM tests |
| M9 | Monetisation | ✅ | Decided: one-time paid — €4.49 base with a 14-day launch price of €2.29, both set in the Play Console (Products › App pricing), so there is no Billing client, no com.android.vending.BILLING permission and no purchase code. Rationale, market anchors and Console steps: MONETISATION. Verified against the release APK: zero billing and zero INTERNET references. The price must be set before the first upload — Play allows paid → free but never free → paid |
| M10 | Store assets | ✅ | Name decided: Plain Files (one string; applicationId already locked). tools/make-store-assets.sh renders the 512×512 RGBA icon and the 1024×500 RGB feature graphic from the app's own vectors, so the store icon is the launcher icon; tools/make-store-screenshots.sh normalises adb captures to Play's 2:1 cap per form factor (phone crop default 93/130 px, tablets 0). STORE_LISTING carries length-checked copy (name 11/30, short 67/80, full 2730/4000), the permissions paragraph the MANAGE_EXTERNAL_STORAGE declaration requires, and the graphics table. The feature graphic's copy was verified to survive Play's centre-square crop by cropping the rendered PNG. Screenshots captured: 5 phone (1080×2160), 4 on a 7-inch tablet (1200×1920) and 4 on a 10-inch tablet (2560×1600), all 24-bit RGB, inside the 2:1 cap. The tablet sets came from AOSP AVDs. The normaliser refuses a capture whose app area is blank, which is how a pure-background capture was caught before it reached the listing |
| M11 | Library views | ✅ | A Libraries section on the root screen — Images, Videos, Audio, Documents, Archives, Recent — each row carrying how many files the index knows of that kind, each opening an ordinary listing (thumbnails, sort, multi-select, details, the existing viewers) answered from the index instead of from a directory. core/FileCategory groups FileKinds and is asserted to leave DIRECTORY, APK and OTHER out deliberately; SearchIndex gained byKind/recent/kindCounts, and SQLite schema v3 adds the derived kind column — the migration rebuilds the table and drops the volume stamps, because a stamp whose rows have gone would make the next search trust an empty index. A library obeys the indexed search's own two rules: the answer comes first with the walk behind it, and every row is confirmed against the filesystem before it is shown. Not included, and recorded in the CHANGELOG as decisions rather than omissions: Downloads and New files, and restoring a library across process death. 308 JVM tests (19 added here) |
| M12 | Duplicate finder | ✅ | Find duplicates in the overflow. Three passes, cheapest first: size (the index's duplicateCandidates query — one query and no reading at all), the first 64 KB of every candidate (a filter that may only rule files out), and the whole file to confirm (domain/DuplicateFinder, SHA-256, cancellable between files and between read buffers). Groups are ordered by reclaimable space; each header states the copies and what they cost; every row carries its folder, because identical names with no paths are unactionable; and nothing is preselected — the delete is the app's ordinary one, through the trash and the undo snackbar. A file that cannot be read is counted and reported rather than skipped, and the empty state says how many files were compared — or that the index has never run and there was nothing to compare. 323 JVM tests (15 added). Verified on the Xiaomi phone against four genuine groups in its own storage; the delete was deliberately not pressed on a device that is not ours — see EDGE_CASE_TESTING |
| M13 | Video thumbnails | ✅ | A video row shows a frame of the video instead of a film icon: images and videos take the same path through Coil, with the video request asking for a frame a second in. One dependency — coil-video at the Coil version already pinned, whose POM adds only coil-core/stdlib/core-ktx — the platform's own MediaMetadataRetriever behind it, no new permission (no READ_MEDIA_VIDEO), and the decoder registered explicitly against an ImageLoader in FileManagerApplication — because R8 strips coil-video's ServiceLoader entry from a release build, which would otherwise have left frames decoding in debug and quietly falling back to icons for real users. A decode that fails settles on the icon rather than an empty square. Verified on the phone against two purpose-made clips and a real video of the device's own, with the demo library's stand-ins falling back as intended, and re-verified on the release APK. 324 JVM tests |
| M14 | Batch rename with sequence continuation | ✅ | Selecting more than one file and choosing Rename opens a pattern dialog: a name, a start number, and a live preview of the names it will produce. core/BatchRename plans the whole batch before a single file moves and returns one of three answers — Ready, Blocked (naming the target the folder already holds) or NothingToDo — with the deliberate absence of a fourth: a batch that renamed nine of twelve and stopped would leave the user to work out which nine. The numbering continues the folder's own series nextNumber from the highest base (n) it finds, which is the market survey's most-helpful complaint answered by name; the extension is kept per file, the series is counted across extensions, and continuing beats filling the first gap. SelectionBar now offers Rename to any selection (one file keeps the name dialog, several get the pattern one), and the batch's renames are one Undo.Relocate step. The same commit hardens the single rename: core/FileNames.isUsableName refuses a name that is not one path segment, because notes/final.txt was being resolved as a path and moved the file instead of renaming it. 350 JVM tests (26 added) |
| M15 | Favourites | ✅ | A star in the app bar of any folder, and a Favourites section on the home screen above the libraries — absent while empty, so a first-time user still meets the libraries first. data/BookmarkStore + SqliteBookmarkStore keep one path per row in their own database: a reference, never a copy, so the list costs one query and no filesystem work. BrowserUiState.Bookmark carries an exists flag, and a folder that has gone is kept and marked rather than deleted — an unmounted card and a deleted folder are the same thing from here — with opening re-checked at that moment so the answer is a message instead of an empty listing. The row's filled star is the removal (the mark that says "favourite" is the thing you tap to stop it being one), there is no star in a library or on the root screen, and no Undo for a bookmark because that type is "the last change to the filesystem" and a favourite is not one. 371 JVM tests (16 added) |
Key decisions
| Decision | Choice | Rationale |
|---|---|---|
| Language / UI | Kotlin + Jetpack Compose | Mirrors the sibling app's proven, installed toolchain; no NDK |
| Storage access | MANAGE_EXTERNAL_STORAGE first, SAF fallback |
Google Play explicitly permits "All files access" for file managers; SAF keeps the app usable if the user declines |
| Connectivity | Local-first (no INTERNET in v1) |
Preserves the "nothing leaves the device" claim and keeps the Data Safety form trivial |
| File sharing | Receives SEND/SEND_MULTIPLE, serves GET_CONTENT/OPEN_DOCUMENT, and deliberately does not register ACTION_VIEW |
A file manager should be able to receive a file and to supply one, and neither costs a permission. Registering as a viewer as well would put Plain Files in the "open with" chooser the app itself uses, offering it back to itself |
| Quality gate | tools/verify.sh — map check, detekt, tests, lint; --release adds R8 — run by CI, by the pre-push hook and by hand |
One command that means the same thing in all three places. The detekt baseline is what makes adopting static analysis possible without a backlog-clearing week, while still failing on anything new |
| Monetisation | One-time paid (€4.49; €2.29 launch price), set in the Console | No Billing client, no BILLING permission, no purchase code — which is what keeps "nothing leaves the device" true in the shipped APK. Free → paid is impossible after the first upload, so the price must be set beforehand. See MONETISATION |
Deliberately deferred (post-1.0)
- Cloud storage (Drive/OneDrive/Dropbox/…); network clients (SMB/FTP/SFTP/WebDAV); FTP/Web
server. All of these need
INTERNET, which is the one permission the app deliberately does not declare — see the connectivity decision above. - App manager (
QUERY_ALL_PACKAGES), APK installation (REQUEST_INSTALL_PACKAGES). - RAR archives (the format needs native code) and 7z creation; root explorer; encryption vault; themes/icon packs.
Candidates from the competitive analysis
A survey of the market leader (its features, and what its users praise and complain about) is in COMPETITIVE_ANALYSIS. Its gaps that cost no new permission are listed there as 💡 candidates. Four of them have since been shipped: category libraries (M11), the duplicate finder (M12), batch rename with sequence continuation (M14) and favourites (M15). What is left — the post-paste "copy again" / "return to source folder" — is a proposal, not scheduled work, and taking it on is a roadmap decision rather than a side effect of reading that document.