properpcloud roadmap

properpcloud roadmap

The roadmap is release-oriented. A feature is complete only when its behavior, failure states, accessibility, persistence, tests, and release evidence are all complete. Dates are intentionally omitted; quality gates, not calendar pressure, determine publication.

0.0.1 — validated architecture bootstrap

Status: released, tagged, and published on GitHub.

Completed:

• Semantic Versioning and immutable annotated tags;
• MIT project license plus bundled Apache-2.0 dependency notices;
• checksum-verified Docker/Gradle toolchain;
• source-neutral folder, queue, progress, inspection, and stream contracts;
• pCloud Java SDK and WebDAV adapter boundaries;
• Media3 service bootstrap;
• normative product, UX, test, build, release, and Linux specifications;
• green specification, unit-test, lint, and debug-APK gate.

The v0.0.1 tag is the immutable baseline and must never be moved.

0.1.0 — first validated Android client

Status: released, tagged, independently audited, attested, and published.

Product promise

0.1.0 is a usable Android application even without provider credentials. It ships a deterministic, locally generated demo library so every browser, queue, playback, persistence, and responsive-UI flow can be validated in CI and by a reviewer. Users who provide their own pCloud application client ID can authorize through pCloud’s trusted surface and use the same folder-first workflow against their account.

Feature-complete scope

Identity and source handling

• Folder/file identity remains source ID plus stable node ID.
• Built-in deterministic demo source requires no network or credentials.
• Native pCloud source uses the official Java SDK.
• OAuth uses the official Android authorization activity.
• Access tokens are encrypted with Android Keystore AES-GCM.
• Only documented US/EU API hosts are accepted.
• Passwords, signed stream URLs, and tokens are never persisted or logged.
• Disconnect removes the local encrypted session immediately.

Folder-first library UX

• Compact bottom navigation and expanded navigation rail.
• Folder breadcrumbs based on stable IDs.
• Folder and track rows preserve filename context.
• Natural filename, disc/track, tagged-title, and modified-time sorting.
• Loading, refresh, empty, error, demo, connected, and partial-result states.
• Metadata/identity inspection with secrets redacted.
• One-action navigation from the player to the containing folder.
• Add containing-folder and metadata-inspection actions directly to every queue row.
• Dynamic system color plus a custom badger/cloud visual identity.

Queue semantics

• Play/replace, play-next, and append for tracks.
• Direct-folder and recursive-subtree queue construction.
• Atomic queue replacement; empty or cancelled scans preserve the old queue.
• Stable-ID duplicate collapse and deterministic ordering.
• Partial traversal records readable omissions rather than silently skipping.
• Select, remove, move-up, move-down, and clear operations.
• Queue order and selected item survive process death.

Playback and progress

• Media3 MediaSessionService and system media controls.
• Stable media IDs; direct links resolved immediately before playback.
• One bounded link refresh on eligible HTTP 401/403 expiry responses.
• Play/pause, previous/next, ±15/30-second seek, timeline, and mini-player.
• Progress checkpoints and revision-ready progress identity.
• Smart rewind after interruptions and completion threshold policy.
• Generated PCM/WAV demo media exercises real ExoPlayer decoding.

Privacy, accessibility, and distribution

• No analytics, mandatory backend, or cleartext network traffic.
• Tokens and app data excluded from Android backup/device transfer.
• Content descriptions, deterministic TalkBack order, and non-color state text.
• Keyboard/non-drag alternatives for queue reorder.
• In-app version, license, dependency notice, and privacy summary.
• Complete string-resource extraction and localization-ready formatting.
• Automated large-font and compact/expanded screenshot review.
• Manual TalkBack pass on a physical or virtual device.

Automated release gates

Every item below is release-blocking:

release_gates:
  metadata:
    - make release-check
    - VERSION == 0.1.0
    - CHANGELOG contains dated 0.1.0 section
    - tag v0.1.0 resolves exactly to release commit
  static:
    - duplicate-key-safe YAML validation
    - git diff --check
    - Android lint has no error or warning findings
  tests:
    - pure queue/progress/sort/identity unit tests
    - pCloud session/host validation tests
    - deterministic demo-source and WAV tests
    - DataStore queue/progress round-trip tests
    - Robolectric Compose compact and expanded navigation tests
    - process-death reconstruction test with stable queue references
  build:
    - pinned Docker image
    - Eclipse Temurin JDK 21 for Android 16 Robolectric compatibility
    - compile SDK 37, target SDK 36
    - debug/demo APK assembly
    - release APK assembly with external signing boundary documented
  evidence:
    - APK SHA-256
    - toolchain image ID
    - JUnit and lint summary
    - third-party notices present in source and APK

External validation gate

No CI credential is embedded. Before describing the pCloud path as live-validated, a maintainer must run the protected sandbox checklist with a registered pCloud application and disposable test account:

1. authorize US and EU regional accounts;
2. browse at least three nested folders and a folder above 500 entries;
3. play and seek an MP3, M4A/M4B, FLAC, Ogg/Opus, and WAV where account data permits;
4. invalidate or age a direct link and verify bounded renewal at the same position;
5. deny, cancel, disconnect, revoke, and restore authorization;
6. kill the process during browse, queue construction, and playback;
7. verify no token or signed URL in logs, backups, reports, or persisted state.

Until this checklist has evidence, release notes must say implementation validated with deterministic fakes; live pCloud account validation outstanding.

0.1.x post-release hardening

Independent read-only UI/UX and release-engineering audits found no blocker for 0.1.0, but identified the following concrete patch-line work before Android semantics are considered frozen for Linux parity:

• add direct MainViewModel orchestration tests with a fake playback controller;
• flush playback progress explicitly on app background and service teardown;
• allow a later retry when a transient failure prevents the one bounded signed-link refresh;
• add containing-folder and metadata-inspection actions to each queue row;
• surface controller-connection and stale-queue-restoration failures to the user;
• convert core-model from an Android library to a pure JVM or multiplatform module;
• verify the committed Gradle wrapper JAR checksum in the release gate;
• pin third-party GitHub Actions by immutable commit SHA and let Dependabot update them.

These are release-quality hardening items, not retroactive changes to the immutable v0.1.0 tag. Product behavior changes ship under a new SemVer tag.

0.1.1 — release-pipeline integrity patch

Status: released, tagged, validated, and published.

• rebuild and publication are bound to one explicit immutable tag;
• all third-party GitHub Actions are pinned to reviewed commit SHAs;
• the committed Gradle Wrapper JAR has a separately reviewed SHA-256 gate;
• release validation rejects floating actions, wrapper drift, and missing release evidence;
• no user-facing playback or library behavior changes.

0.1.2 — modern player and metadata foundations

Status: released, tagged, validated, and published.

• dedicated seekable now-playing destination while preserving folder-first identity;
• compact queue actions and grouped metadata inspection;
• canonical tag snapshots, provenance, confidence, patches, and batch edit plans;
• real jaudiotagger-backed local inspection and copy-on-write staged mutation;
• SHA-256 source guard plus staged reread and field verification;
• identified, HTTPS, serialized MusicBrainz search with secure XML parsing;
• Cover Art Archive and AcoustID/Chromaprint contracts without embedded keys;
• comprehensive UX and guarded remote metadata-maintenance specifications.

Remote pCloud file replacement is not enabled in this release. It remains gated on exact-revision download, conditional replace, provider readback, audit, and indeterminate-state reconciliation.

0.1.3 — reviewed Tag studio and safe export

Status: local release candidate.

• in-app single-file editor with original values and provenance;
• bounded 20-file batch selection, common fields, explicit clears, and sequencing;
• field-level MusicBrainz proposal review;
• exact pCloud source preparation with provider SHA-256 and pre/post revision checks;
• reread-verified single audio export or ZIP plus CSV manifest;
• scoped FileProvider sharing and bounded private-file retention;
• no remote overwrite because the current pCloud SDK lacks atomic expected-revision replacement.

0.1.4 — ordinary OAuth onboarding and complete disconnect

Status: local release candidate.

• public application client ID injected into tagged builds for one-tap pCloud sign-in;
• no user-created app, copied token, or pasted ID in the ordinary path;
• explicit personal/developer client-ID override retained under advanced setup;
• tagged release validates a supplied application ID; while pCloud registration is unavailable, releases may ship with the interim direct-login fallback;
• local credential removal and source detachment happen before network revocation;
• queues containing pCloud media are cleared so an already-resolved stream cannot continue;
• regional /logout invalidation uses an HTTPS bearer header and typed safe outcomes.

External gate: register the properpcloud pCloud application once, configure pcloud-oauth://dev.properpcloud.app, enable implicit grant, set the public PCLOUD_CLIENT_ID repository variable, and complete protected US/EU live tests. The provider console is currently unavailable for this account, so this remains an enhancement gate rather than a blocker for the interim direct-login release.

0.1.5 — Android semantic freeze and lifecycle hardening

Status: local release candidate.

• direct MainViewModel orchestration tests through an injected playback-controller port;
• explicit progress flush on app background, ViewModel/service teardown, queue switch, manual transition, disconnect, playback error, and task removal;
• one immediate signed-link retry plus a later retry after cooldown;
• controller connection/restoration failures represented in UI state instead of silent fallback;
• stale persisted queues repaired and rewritten with explicit user notice;
• Android queue/progress serialization fixtures frozen and byte-replayed as the 0.2.0 corpus.

External gates remain: physical-device process-death during browse, recursive queue construction, playback, metadata staging, OAuth return and disconnect; TalkBack, 200% font, media keys, headset/codec behavior, and Android 17 runtime validation.

0.1.6 — interim direct login and account UX

Status: release target.

• preserve OAuth as the preferred login path whenever a registered public client ID exists;
• add pCloud’s documented username/password → auth token flow as a visibly interim fallback;
• require explicit Europe/United States selection and send credentials to exactly one allowlisted HTTPS host;
• clear password form state before dispatch, never persist/log/export it, and request bounded token lifetimes;
• persist token kind so OAuth bearer and legacy auth sessions restore with the correct transport;
• move legacy SDK method parameters and token from URLs to HTTPS form POST bodies;
• perform token-kind-aware provider logout after local-first disconnect;
• allow tagged evaluation releases without PCLOUD_CLIENT_ID while continuing to validate any supplied ID;
• replace the broken documentation SVG with the supplied PNG logo and use it in the in-app About surface;
• keep two-factor direct-login support explicitly unclaimed until protected live-account evidence exists.

OAuth application registration, protected EU/US direct-login checks, and two-factor behavior remain external provider/device gates. The direct path is temporary and will become a fallback-only option once OAuth application registration succeeds.

Deferred beyond 0.1.0

• verified offline file pinning and storage quotas;
• saved-root tabs and whitelist/blacklist policy editor;
• guarded pCloud replacement only after an atomic provider primitive exists;
• Android Auto browse hierarchy;
• bookmarks, sleep timer, variable speed policy, and aggregate book progress;
• cross-device progress synchronization.

0.2.0 — native Linux desktop parity

Status: functional native implementation complete; packaging and protected live validation remain release gates.

Completed implementation:

1. core-model, pCloud, WebDAV, metadata-online, and metadata-tags build as plain JVM modules without Android linkage.
2. Compose Desktop three-pane library, inspector, queue, and bottom-player shell.
3. deterministic direct and recursive folder queues with shared sorting/reducer semantics.
4. SQLite settings, queue, and progress persistence under XDG data paths.
5. freedesktop Secret Service session-token storage with no plaintext fallback.
6. mpv child-process supervision over private Unix JSON IPC with --no-config.
7. fresh pCloud stream resolution, play/pause/seek/next/previous, and smart resume.
8. MPRIS root/player service and media-state publication.
9. deterministic generated-WAV demo source and real-host mpv/SQLite smoke entry point.
10. Compose Desktop application-image plus .deb/.rpm packaging configuration.

Remaining release sequence:

1. protected EU and US pCloud account playback, expiry, disconnect, and restart evidence;
2. browser OAuth after the desktop redirect registration is confirmed with pCloud;
3. GNOME, KDE Plasma, and i3 Secret Service/MPRIS validation;
4. keyboard-only, high-contrast, font-scaling, and accessibility review;
5. reproducible Arch and broad-distribution artifacts with license review;
6. long-duration playback and forced mpv crash/recovery soak tests.

0.2.0 is not an Android feature bucket. It delivers a native Linux desktop client over the shared source-neutral contract; only the listed release evidence remains.

Reuse boundary

Shared without Android dependencies:

• source/node identity and folder model;
• sorting, queue reducer, recursive assembler, omission model;
• progress, completion, and smart-rewind policy;
• pCloud java-core adapter and source contract tests;
• serialized queue/progress records and migration fixtures;
• redaction, error taxonomy, and inspection records.

Native Linux adapters:

• Compose Multiplatform Desktop UI;
• system-browser OAuth and Secret Service/KWallet storage;
• SQLite persistence under XDG paths;
• mpv JSON IPC playback with expiring-link renewal;
• MPRIS, media keys, notifications, and desktop file integration.

Desktop product gates

0_2_0_parity:
  library:
    - folder tree, breadcrumbs, search scope, and raw filename context
    - same sort behavior and containing-folder navigation as Android
  queue:
    - same reducer fixtures and queue snapshot format
    - mouse, keyboard, and context-menu operations
  playback:
    - mpv process supervision
    - MPRIS controls and position
    - crash/restart resumes from durable queue and progress
  security:
    - token only in Secret Service/KWallet
    - private IPC socket under XDG_RUNTIME_DIR
    - no signed URL in command history, logs, or playlist files
  accessibility:
    - full keyboard operation
    - no drag-only action
    - semantic accessibility bridge and high-contrast review
  packaging:
    - Gradle distribution and Arch package
    - Flatpak with browser/secret-service/mpv portal review
  compatibility:
    - GNOME, KDE Plasma, and i3 validation

The detailed architecture is in spec/linux-client.yml and docs/linux-client.md.

0.3.0 — durable offline and long-form power features

• verified file/folder/subtree pinning and cache accounting;
• saved roots, custom tabs, whitelist/blacklist rules;
• variable speed, sleep timer, bookmarks, and aggregate progress;
• Android Auto and richer external media browsing;
• optional local/FUSE source.

0.4.0 — transparent metadata intelligence

• embedded metadata parsing with raw/normalized/effective views;
• filename/path inference and explicit external-provider consent;
• candidate confidence/provenance and dry-run field diffs;
• no remote writes.

0.5.0 — revision-safe metadata maintenance

• staged edits against an expected revision/hash;
• decode and tag validation before upload;
• post-upload readback verification;
• conflict handling, audit trail, and recovery revision.

1.0.0 — stable cross-platform contract

1.0.0 requires stable migrations, documented public contracts, Android and Linux release lines, complete privacy/security review, reproducible signed artifacts, and compatibility guarantees for queue/progress/source records.