SoftwareApp
ddae70a8bc
The first question about any change is which file it belongs in, and the three documents that
kept being asked to answer it - README (the tour), ROADMAP (what is done) and CHANGELOG (why it is
like that) - were never going to. docs/CODE_MAP.md answers it: all 74 source files with the purpose
taken from the KDoc already sitting next to them, their size, and the tests that cover them,
followed by every test name in the suite. Those names are sentences about behaviour in this project
("a batch rename is a single undo step"), so the index doubles as the specification, and it is the
cheapest way for a reader, human or otherwise, to find out whether something is already covered.
The map is generated by tools/make-code-map.py rather than written, because a hand-maintained
description of 74 files is wrong within a milestone and nobody notices. The script harvests
declarations and comments; --check fails the moment the file stops matching the tree, and it caught
this very change (350 tests to 355); and the file says so about itself in its first line. A file is
described by the KDoc of the declaration that shares its name, which is the convention this
codebase already follows, and where no declaration matches, the first KDoc is used and the file is
listed at the end - so 15 fallbacks out of 74 are visible rather than assumed. Test files are
attached by the class they declare (NameTest -> Name.kt), which is a name-based match and therefore
approximate: the one honest weakness, and worth knowing before trusting a row that says a file has
no tests.
AGENTS.md is the one page that points at the map: what the app is, the two files to read before the
source, the exact commands, the layout with its dependency direction (ui -> domain -> data -> core,
with core free of Android), the rules that have tests behind them, what to read on demand and what
not to read at all, the definition of done, and the traps that have cost real time here - MIUI's two
install gates, assembleDebug racing an adb install, R8 stripping what only a resource names, and adb
input text not delivering a slash.
The same pass made four of the project's stated rules fail instead of merely being stated, in
ProjectInvariantsTest, which reads the source tree: core/ imports no Android (the engine stays
testable without Robolectric), no Text(...) in ui/ is handed a string literal (text comes from
strings.xml, which the pseudo-locale build exercises), the manifest requests exactly the six
permissions the app is built around and never INTERNET, and separator handling lives in core/ alone.
Three of the four were already true. The fourth found a bug: createFolder checked only that the name
was not empty, so "notes/final" was resolved by StoragePath into the notes folder that happened to
exist - the dialog offered one folder in the folder on screen and the app created a different one.
Rename refused the same input, because the rule has exactly one implementation and only one of its
two callers used it.
Both callers now go through isUsableName, and the shared name dialog says why a name is refused -
"A name cannot contain a slash", while it is typed, with its button disabled - rather than appearing
to do nothing when it is pressed. The batch dialog and both single-name dialogs read the same
string, so the rule reads the same wherever a name is entered. Verified on the phone: a slash typed
into New folder shows the note with Create the only disabled node in the dump, and deleting the
slash clears the note and re-enables it.
355 JVM tests (5 added: the four invariants and the folder-name refusal), lint clean, the map
current. The source-level rules state their own limits in their comments - the literal rule catches
a literal as the whole text of a Text(...) and not one concatenated into resource text, because
seeing that would take a Kotlin parser, and a rule that pretends otherwise is worse than one that
says where it stops.
227 lines
12 KiB
Markdown
227 lines
12 KiB
Markdown
# File Manager
|
||
|
||
An **ad-free**, **one-time-paid** Android file manager. It browses and manages the
|
||
files on your device — locally, with no ads, no account and no analytics.
|
||
|
||
Nothing ever leaves the device: the app declares no network permission and contains
|
||
no advertising or tracking SDKs.
|
||
|
||
> **Working title.** The display name and the store listing are decided before the
|
||
> first Play upload (see [docs/ROADMAP.md](docs/ROADMAP.md), M10). The `applicationId`
|
||
> is already fixed and can never change after the first release.
|
||
|
||
## Status
|
||
|
||
**M14 — renaming a batch: done.** Selecting several files and choosing Rename opens a **pattern**
|
||
dialog instead of the single-file one: one name, the number to start at, and a preview of the names
|
||
it will produce — and the numbering **carries on from the folder's own**, so `series (1)` and
|
||
`series (2)` already there make the next batch start at 3. A batch that cannot be done is refused
|
||
before anything moves, naming the file in the way, and the whole batch is one undo step. Before it:
|
||
**M13 — video thumbnails** (a video row shows a frame of the video itself rather than a film icon —
|
||
the platform's own retriever, through Coil, with a frame taken a second in and the icon kept as the
|
||
fallback when a file cannot be decoded), **M12 — duplicate finder** (size, then the head of every
|
||
candidate, then the survivors in full), **M11 — library views** (a **Libraries**
|
||
section on the root screen — Images, Videos, Audio, Documents, Archives and Recent — whose rows open
|
||
ordinary listings of those files, each carrying a count from the search index), and **M10 — store
|
||
assets**: the app is named **Plain Files**, the icon and feature graphic come from the app's own
|
||
vectors, and [docs/STORE_LISTING.md](docs/STORE_LISTING.md) holds length-checked listing copy.
|
||
Screenshots exist for 5 phone (1080×2160), 4 on a 7-inch tablet (1200×1920) and 4 on a 10-inch
|
||
tablet (2560×1600) — but they **predate M11**, so the home screen in them is the old volume list and
|
||
they will need re-shooting, which the library views make a privacy question as well as a cosmetic one
|
||
([docs/STORE_LISTING.md](docs/STORE_LISTING.md)).
|
||
|
||
## Tech stack
|
||
|
||
| Area | Choice |
|
||
|---|---|
|
||
| Language | Kotlin 2.4.10 (using AGP 9 *built-in Kotlin*) |
|
||
| UI | Jetpack Compose, BOM 2026.06.01, Material 3 |
|
||
| Build | Gradle 9.3.1, Android Gradle Plugin 9.1.0 |
|
||
| Storage access | `MANAGE_EXTERNAL_STORAGE` ("All files access") with a Storage Access Framework fallback |
|
||
| Archives | Apache Commons Compress + XZ for Java (both pure Java — no NDK) |
|
||
| SDK levels | `compileSdk`/`targetSdk` 36, `minSdk` 26 |
|
||
|
||
`targetSdk` is 36 because Google Play requires new apps and updates to target
|
||
Android 16 (API 36) from 31 August 2026.
|
||
|
||
## Project layout
|
||
|
||
```
|
||
app/src/main/java/de/softwareapp_hb/filemanager/
|
||
├── core/ Pure-Kotlin engine (no Android imports!) — paths, sorting, formatting,
|
||
│ search matching, copy/move planning, conflict policy
|
||
├── data/ Storage backends (all-files access + SAF), volumes, shares coming in
|
||
│ from other apps, the trash index (SQLite), file operations, archives,
|
||
│ deletion
|
||
├── domain/ Browser + operation controllers, models, permission state
|
||
├── service/ Foreground service for long-running file operations
|
||
├── ui/ Compose theme, browser screen, components, ViewModels
|
||
└── text/ Domain enum → string-resource mapping
|
||
app/src/test/java/… JVM unit tests for the core engine
|
||
```
|
||
|
||
`core/` deliberately has **no Android dependencies**, so the trickiest logic is
|
||
covered by fast JVM tests.
|
||
|
||
The per-file index — what each file holds, and every test name in the suite — is
|
||
[`docs/CODE_MAP.md`](docs/CODE_MAP.md), generated from the source by
|
||
`tools/make-code-map.py` (`--check` fails when it is stale). [`AGENTS.md`](AGENTS.md) is the
|
||
one-page briefing for whoever picks the repository up: the commands, the layout and its
|
||
dependency direction, the rules that have tests behind them, and the traps worth knowing
|
||
before spending an hour on them.
|
||
|
||
## Building
|
||
|
||
Prerequisites:
|
||
|
||
- JDK 17+ (JDK 25 verified)
|
||
- Android SDK with `platforms;android-36` and `build-tools;36.0.0`
|
||
|
||
```bash
|
||
# Tell Gradle where the SDK lives (this file is git-ignored)
|
||
echo "sdk.dir=$HOME/Android/Sdk" > local.properties
|
||
|
||
./gradlew :app:assembleDebug # debug APK
|
||
./gradlew :app:testDebugUnitTest # JVM unit tests for the engine
|
||
./gradlew :app:lintDebug # Android Lint
|
||
./gradlew :app:bundleRelease # Play upload bundle (.aab)
|
||
```
|
||
|
||
Release signing is optional and driven by a git-ignored `keystore.properties`
|
||
(see `keystore.properties.example`); without it the release build still runs
|
||
R8/minification but produces an unsigned artefact.
|
||
|
||
## Tracked in git
|
||
|
||
- Source, resources and Gradle build files.
|
||
- `docs/` — the roadmap, the generated code map and the release documentation.
|
||
- `PRIVACY.md`, `CHANGELOG.md`, `AGENTS.md`, and (from M10) `store-assets/`.
|
||
|
||
Not tracked: `local.properties`, `keystore.properties`, `*.jks`, build outputs.
|
||
|
||
## Releasing
|
||
|
||
Release signing is driven by the git-ignored `keystore.properties` (see
|
||
`keystore.properties.example`). Without that file the release build still runs R8 and
|
||
resource shrinking, but produces an unsigned artefact that cannot be uploaded.
|
||
|
||
```bash
|
||
./gradlew :app:bundleRelease # Play upload bundle (.aab)
|
||
./gradlew :app:assembleRelease # APK, for local checks
|
||
|
||
# Audit what is actually shipped — in particular that there is no INTERNET permission:
|
||
$ANDROID_HOME/build-tools/36.0.0/aapt2 dump permissions \
|
||
app/build/outputs/apk/release/app-release.apk
|
||
```
|
||
|
||
Read [docs/PLAY_RELEASE_CHECKLIST.md](docs/PLAY_RELEASE_CHECKLIST.md) before uploading.
|
||
Step 4 is the one that matters most for this app: a file manager must declare **"All files
|
||
access"** through Play's Permissions Declaration Form, and have the core purpose documented
|
||
in its store description. [PRIVACY.md](PRIVACY.md) is written to match the shipped
|
||
permissions.
|
||
|
||
## Localisation
|
||
|
||
All user-visible text lives in `app/src/main/res/values/strings.xml`, with real `<plurals>`
|
||
wherever a count can be one, and the screen and the progress notification resolve their
|
||
labels through `text/TextRes.kt` so the two cannot drift apart. **English is currently the
|
||
only locale.**
|
||
|
||
Adding a language is then a file, not a refactor:
|
||
|
||
```
|
||
app/src/main/res/values-de/strings.xml # same keys, translated values
|
||
```
|
||
|
||
Deliberately **not** localised, and why:
|
||
|
||
- **Byte units** ("KB", "MB") — symbols, not words, and every file manager and the system
|
||
Settings app show them the same way.
|
||
- **The timestamp pattern** (`yyyy-MM-dd HH:mm`) — a fixed, sortable format; the zone is
|
||
passed in explicitly rather than assumed.
|
||
|
||
### Checking that nothing was missed
|
||
|
||
Two things are easy to get wrong: a literal typed into a composable, and showing an enum
|
||
constant directly (`FileKind.name` puts untranslatable English on screen — the details
|
||
sheet used to do exactly that). The mechanical check is the pseudo-locale:
|
||
|
||
```bash
|
||
./gradlew :app:assembleDebug
|
||
# Settings > System > Languages > English (XA), then launch the debug build.
|
||
```
|
||
|
||
The debug build type sets `isPseudoLocalesEnabled = true`, so every string that came from
|
||
`strings.xml` renders accented and bracketed (`[Îmàgé]`). **Anything that looks normal is a
|
||
string that never went through resources.** The release build is unaffected.
|
||
|
||
One caveat: **Google Play's automatic translation translates your store listing, not the app
|
||
UI.** Translated UI text has to be supplied in `values-<locale>/`.
|
||
|
||
## Known limitations
|
||
|
||
- **The trash is a time window, not a bin you manage.** A delete stages the item in a hidden
|
||
`.plainfiles-trash` folder on the same volume and keeps it for 24 hours; the **Trash** entry
|
||
in the overflow menu lists what is still there and puts a whole batch back. There is no
|
||
"empty it now" action — expired batches are swept the next time something is deleted — and a
|
||
name taken again in the meantime is never overwritten, so a restored item can arrive beside
|
||
the new one rather than replacing it.
|
||
- **Where a trashed item came from is remembered in the app's own database**, not on the
|
||
volume. The staged files are the truth and the database is only an index, so the two are
|
||
reconciled in both directions: an entry whose file has gone is not offered back, and a
|
||
batch folder no entry mentions is swept.
|
||
- **Sharing a file *out* only works in the all-files mode.** A SAF path is relative to the
|
||
granted tree rather than a filesystem path, so it cannot be handed to `FileProvider`.
|
||
Receiving a share and being picked from another app's chooser work either way: the first
|
||
needs no filesystem path, and the second falls back to `RESULT_CANCELED` rather than
|
||
returning a URI the caller could not read.
|
||
- **RAR, CAB, ISO and WIM are refused**, not supported — they need native code, which this
|
||
project deliberately does not ship. (The Commons Compress jar contains no RAR classes at
|
||
all.) **7z is different**: Commons Compress reads it in pure Java, so it *is* supported —
|
||
but the format needs a seekable channel rather than a stream, because its header lives at
|
||
the end of the file. All-files access can supply one; the SAF fallback cannot, so 7z
|
||
extraction reports that plainly in folder mode instead of half-working.
|
||
- **7z files can be opened but not created** — writing stays ZIP-only.
|
||
- **Archive extraction does not restore original timestamps or permissions**, and there is
|
||
no archive encryption or password support.
|
||
- **Cancellation happens between entries**, so a single very large file finishes before a
|
||
stop is honoured.
|
||
- **A batch rename is refused rather than half-done when one of its names is taken**, including when
|
||
the file holding that name is part of the same batch: `a.txt` taking `a (1).txt` while `a (1).txt`
|
||
is itself being renamed needs the files shuffled through temporary names, so the dialog names the
|
||
file in the way instead. Renaming in the other order, or starting the numbering past the block,
|
||
does what you want.
|
||
- **A library is not restored across process death.** The persisted view state holds a path, and a
|
||
library has none, so a restart returns to the root screen rather than to Images or Recent.
|
||
- **Long-press multi-select is awkward to script from the host.** The gesture that opens the
|
||
selection bar (`input swipe x y x y 900`) works on the MIUI test device but has also
|
||
registered as a plain tap, so compress/extract from the UI wants a manual pass (see
|
||
[docs/EDGE_CASE_TESTING.md](docs/EDGE_CASE_TESTING.md)).
|
||
- The display name is still the working title — decided before the first upload (M10).
|
||
|
||
## Monetisation
|
||
|
||
**One-time paid: €4.49 base, with a €2.29 launch price for the first 14 days.** No ads, no
|
||
subscription, no in-app purchases, no free tier.
|
||
|
||
The price lives on the Play listing, not in the build, which is why there is no Billing
|
||
client in the dependencies and no `com.android.vending.BILLING` permission in the APK —
|
||
that is what keeps "no network permission, nothing leaves your device" true of the
|
||
*shipped artefact* rather than just the source. Rationale, market anchors, the rejected
|
||
alternatives and the Console steps: [docs/MONETISATION.md](docs/MONETISATION.md).
|
||
|
||
⚠️ **The price must be set before the first upload** — Play allows paid → free but never
|
||
free → paid.
|
||
|
||
## Competitive context
|
||
|
||
The category leader is **File Manager Plus** (AlphaInventor; 100 M+ installs, 4.7–4.8★, free
|
||
with ads and in-app purchases, and a Data Safety form that shares device IDs with third
|
||
parties). What it offers, what its users praise, what they complain about, and which of those
|
||
complaints this app can answer without asking for a single new permission:
|
||
[docs/COMPETITIVE_ANALYSIS.md](docs/COMPETITIVE_ANALYSIS.md).
|
||
|
||
## Licence
|
||
|
||
Proprietary — all rights reserved.
|