Ubisam-MobileGit/tasks/036-favorite-repo-push-notifications.md

# TASK-036: Push notification when a favorited repository gets a new push

Status: implemented; all required checks pass; live-installed, awaiting the human product owner's confirmation
Owner: Claude
Reviewer: Codex

## Outcome

The human product owner asked earlier this session for a notification when a repository they've
favorited receives a push, explicitly accepting it was fine to skip if infeasible. Feasibility was
already established (see TASK-029's dev-log entry) and the human product owner approved building it
as its own task. Gitea's own server-side notification feed doesn't fire for plain pushes (only
issue/PR activity), so this can't be reached via the existing `/notifications` integration — the
app now periodically checks each favorited repository's most recent push time itself (reusing the
exact detection heuristic `RepositoryListViewModel` already uses for "last pushed branch": the
newest branch commit timestamp) and posts a local notification when it advances past what was last
seen.

## Scope

- Included: `androidx.work:work-runtime-ktx` dependency; new `core/notifications/` package
  (`FavoritePushDetector`, `LastSeenPushStore` + Android impl, `GetLatestPushEpochMillisUseCase`,
  `FavoritePushCheckWorker`, `FavoritePushNotifier`, `FavoritePushScheduler`); `POST_NOTIFICATIONS`
  manifest permission + runtime request wiring in `MainActivity`; a notification channel.
- Excluded: No deep link from the notification into the specific repository — tapping it opens the
  app to its normal entry point, not that repository directly (see Design notes). No change to
  Gitea's own `/notifications` feed or the existing in-app Notifications screen — this is a
  separate, local-only notification channel. No UI to configure the check interval or disable this
  per-repository — it's on for every favorited repository, or off entirely if the OS permission is
  denied.

## Writable paths

- `app/build.gradle.kts`, `gradle/libs.versions.toml`
- `app/src/main/AndroidManifest.xml`
- `app/src/main/java/com/ubisam/ubgitea/core/notifications/`
- `app/src/main/java/com/ubisam/ubgitea/domain/usecase/RepositoryBrowseUseCases.kt`
- `app/src/main/java/com/ubisam/ubgitea/MainActivity.kt`
- `app/src/test/java/com/ubisam/ubgitea/core/notifications/`
- `tasks/036-favorite-repo-push-notifications.md`, `docs/development-log.md`

## Design notes

- **Detection reuses a verified heuristic instead of inventing a new one**: "last push" is derived
  the same way `RepositoryListViewModel.launchRowBranchFetch` already derives it for the repository
  list's "마지막 push" row — the maximum `commitAtEpochMillis` across a repository's branches, via
  Gitea's existing `/branches` endpoint. `GetLatestPushEpochMillisUseCase` in
  `RepositoryBrowseUseCases.kt` packages that exact algorithm (paginate all branches, take the max
  commit time) as its own reusable use case rather than duplicating an ad hoc copy inside the new
  worker; the ViewModel's own existing code path is untouched (lower-risk than refactoring already-
  tested, currently-working code just for this).
- **First sight of a repository never fires a notification**: `FavoritePushDetector.detectNewPushes`
  only reports a repository as "newly pushed" when a previously-recorded timestamp exists AND the
  freshly-fetched one is strictly greater. A repository the store has never seen before (first
  worker run after favoriting it, or the very first run after installing this feature) just
  establishes its baseline silently — without this, the very first background check after adopting
  this feature would fire one notification per already-favorited repository regardless of whether
  anything actually changed recently, which would read as broken/spammy on day one.
- **Storage is plain `SharedPreferences`, not Room**: `docs/architecture.md` reserves Room for
  "when offline caching is approved" — this isn't caching, it's one `long` per favorited repository
  (a coordinates string key, an epoch-millis value), well inside what `SharedPreferences` handles
  cleanly without pulling in a database dependency for a handful of key-value pairs.
- **Scheduled unconditionally on app start, gated internally instead**: `FavoritePushScheduler`'s
  `WorkManager.enqueueUniquePeriodicWork(..., ExistingPeriodicWorkPolicy.KEEP, ...)` is called from
  `MainActivity.onCreate()` every launch — idempotent (`KEEP` means a second call while one is
  already scheduled is a no-op), so it doesn't need its own "is the user logged in" gate at the call
  site. Instead, `FavoritePushCheckWorker.doWork()` itself checks whether a session exists and
  returns `Result.success()` immediately if not (an empty favorites list, or no stored token, is
  simply nothing to check) rather than the scheduler needing to track login state separately.
- **15-minute interval, matching `PeriodicWorkRequest.MIN_PERIODIC_INTERVAL_MILLIS`**: Android's
  own platform floor for periodic `WorkManager` jobs — this was communicated to the human product
  owner as the expected cadence when feasibility was first raised, and there's no reason to poll
  less often than the platform allows for something this low-urgency. `Constraints.NetworkType.CONNECTED`
  is required so the job doesn't even attempt to run while offline.
- **`POST_NOTIFICATIONS` requested once, from `MainActivity`, only where it's needed (API 33+)**:
  below API 33 no runtime prompt exists for notifications at all; on API 33+, the permission is
  requested via `ActivityResultContracts.RequestPermission()` on launch. A denial isn't treated as
  an error anywhere in this feature — `NotificationManagerCompat.notify()` silently no-ops without
  the permission, so the worker still runs and updates its stored baseline correctly either way,
  the user just doesn't see the notification.
- **No deep link yet**: the notification's tap target opens the app at its normal entry point, not
  the specific repository that pushed. Building a genuine deep link would mean extending this app's
  custom sealed `Route` navigation to accept an externally-supplied target and wiring that through
  `MainActivity`'s intent handling — a meaningful chunk of additional, separable work not folded
  into this task; noted as a natural follow-up rather than attempted here.

## Acceptance criteria

- [x] A periodic background check (15-minute `WorkManager` interval, network-constrained) compares
      each favorited repository's latest branch-commit time against what was last recorded.
- [x] A repository seen for the first time by the checker never triggers a notification on that
      first sighting — only a real advance past a previously-recorded timestamp does.
- [x] A local notification is posted (title/body naming the repository) when a favorited
      repository's last-push time advances.
- [x] `POST_NOTIFICATIONS` is requested at runtime on API 33+ and declared in the manifest; the
      feature degrades safely (worker still runs, no crash, notification just doesn't show) if
      denied.
- [x] The worker is a no-op (not a crash, not a spurious notification) when there's no stored
      session or no favorited repositories.
- [x] Build, unit tests, and lint pass.
- [x] Live-confirmed: the `POST_NOTIFICATIONS` runtime prompt actually appeared on the device on
      first launch and was granted (verified after the fact via
      `dumpsys package com.ubisam.ubgitea`, `granted=true`); app launch and the scheduling call
      produced no crash (`logcat` clean of `FATAL EXCEPTION`/`AndroidRuntime` for this app).
- [ ] Not yet live-confirmed: an actual notification firing end-to-end. That specifically requires
      a real push landing on a favorited repository and the 15-minute interval elapsing, which
      doesn't fit inside this same live-testing session.

## Security and privacy

- No new personal data leaves the device — the worker calls the same Gitea API endpoints
  (`/user/starred`, `/repos/{owner}/{repo}/branches`) this app already calls elsewhere, using the
  same shared, Keystore-backed token provider (`AuthSession`), over the same shared HTTPS
  `OkHttpClient`. Nothing is logged beyond this app's existing debug-build-only diagnostic logging
  conventions.
- The stored "last seen push time" data (`SharedPreferences`) contains only repository coordinates
  and epoch-millisecond timestamps — no tokens, no commit content, no user data beyond what's
  already visible in the repository list itself.
- `POST_NOTIFICATIONS` is the only new permission; it grants no capability beyond showing
  notifications this app itself posts.

## Required checks

```text
./gradlew compileDebugKotlin compileDebugUnitTestKotlin
./gradlew testDebugUnitTest
./gradlew assembleDebug lintDebug
```

## Evidence

- `gradle/libs.versions.toml` / `app/build.gradle.kts`: `androidx.work:work-runtime-ktx` 2.11.2
  (latest stable, confirmed against Google's Maven metadata before pinning it) added as a real
  dependency; `work-testing` added test-only.
- `core/notifications/FavoritePushDetector.kt`: pure comparison logic (`current` vs `lastSeen` maps
  → the list of repositories that count as newly pushed), no Android/network dependency.
- `core/notifications/LastSeenPushStore.kt` (+ `SharedPreferencesLastSeenPushStore`): read/write a
  `Map<RepositoryCoordinates, Long>`, `SharedPreferences`-backed.
- `RepositoryBrowseUseCases.kt`: new `GetLatestPushEpochMillisUseCase`.
- `core/notifications/FavoritePushNotifier.kt`: notification channel creation + posting, isolated
  from the worker so it's a thin, directly-inspectable seam.
- `core/notifications/FavoritePushCheckWorker.kt`: `CoroutineWorker` wiring the above together;
  no-ops cleanly on no session / no favorites / any thrown failure (retries transient failures via
  `Result.retry()`, matching `WorkManager` convention).
- `core/notifications/FavoritePushScheduler.kt`: `enqueueUniquePeriodicWork` with a 15-minute
  interval and a network constraint.
- `MainActivity.kt`: schedules the periodic work on launch; requests `POST_NOTIFICATIONS` at
  runtime on API 33+.
- `AndroidManifest.xml`: `POST_NOTIFICATIONS` permission declared.
- New tests: `FavoritePushDetectorTest.kt` (first-sight-never-notifies, an actual advance notifies,
  an unchanged or older timestamp doesn't, multiple repositories are evaluated independently).
- `./gradlew compileDebugKotlin compileDebugUnitTestKotlin`: BUILD SUCCESSFUL.
- `./gradlew testDebugUnitTest`: BUILD SUCCESSFUL, all unit tests passing.
- `./gradlew assembleDebug lintDebug`: BUILD SUCCESSFUL, 0 lint errors.
- Installed on the human product owner's device over wireless `adb`. Live-observed: app launch
  triggered the `POST_NOTIFICATIONS` runtime prompt, which was granted (confirmed via
  `dumpsys package com.ubisam.ubgitea` showing `granted=true`); no crash in `logcat` around launch
  or scheduling. Not yet live-observed: the worker actually firing a notification, since that
  requires a real push landing on a favorited repository and the 15-minute interval elapsing, which
  doesn't fit inside this same live-testing session.

## Known limitations

- No deep link from the notification to the specific repository (see Design notes) — tapping it
  just opens the app normally.
- No in-app way to disable this per-repository or change the interval; it's implicitly on for every
  favorited repository as long as the OS notification permission is granted.
- If the human product owner un-favorites a repository, its stored baseline is dropped on the very
  next successful worker run (`store.write(current)` replaces the whole snapshot with exactly that
  run's favorited set each time) — re-favoriting it later is treated as a first sighting again, not
  a retroactive notification for whatever happened while it was un-favorited. Judged the safer,
  simpler default over trying to preserve and reconcile a stale baseline across that gap.
- `androidx.work` merges its own manifest permissions into the final app (`FOREGROUND_SERVICE`,
  `RECEIVE_BOOT_COMPLETED`) — both normal-level, granted automatically at install time, not
  something this task requested or needs to request at runtime; noted here only so a manifest diff
  doesn't look unexplained.
- Actual end-to-end delivery of a real notification hasn't been observed yet in this session (see
  Acceptance criteria) — the worker's logic is unit-tested, and the scheduling/permission wiring is
  confirmed working live (the runtime prompt appeared and was granted, no crash on launch), but a
  real push landing, 15 minutes elapsing, and a notification actually appearing in the system tray
  is still unconfirmed.

## Review findings

None yet — pending Codex/human review.