CCCT-2440 Connect App Launch For Remaining Pages And Back Navigation

[conroy-ricketts]

CCCT-2440

Stacked on top of CCCT-2439-connect-login-silent-launch-path — review/merge that first.

Product Description

Extends the no-login-screen Connect app launch to the remaining priority entry points and makes back navigation between the app and Connect consistent:

• Launching a CommCare app from the Delivery Progress and Learning Progress pages now opens it directly (single loading dialog) instead of flashing the login and app-setup screens.
• From a Connect-launched app's home screen, back returns to the Connect opportunities list (ending the app session).
• View Job Status on the app home opens the job's progress page on top of the live home; backing out of it returns to the app home, then back again returns to the opportunities list.
• A job progress page opened directly from the opportunities list still backs out to the opportunities list.

Screen_Recording_20260609_113107_CommCare.Debug.mp4

Technical Summary

• Extracts the launch/dialog/outcome-routing wiring that lived in ConnectJobsListsFragment into a shared ConnectAppLaunchController, and routes all three Connect launch surfaces (jobs list, delivery progress, learning progress) through it.
• Home is launched for result; a back-out (RESULT_CANCELED) ends the app session and returns to the opportunities list via ConnectNavHelper.goToConnectJobsList(clearTop = true).
• userPressedOpportunityStatus ("View Job Status") now launches the job-status page on top of the still-live home instead of finishing it, preserving back-to-home.
• The progress dialog is driven by a small pure LaunchProgressMapper → LaunchDialogState; dialog cleanup is handled by a view-lifecycle observer so callers don't manage it.
• Removes dead code surfaced in review (the unused static HomeScreenBaseActivity.launchHome and ConnectAppUtils.getPasswordOverride/shouldOverridePassword).

Safety Assurance

Safety story

What gives confidence:

• I ran the app and exercised the launch and back-navigation flows on a device.
• The diff is scoped to the Connect launch surfaces; the shared controller centralizes logic that was previously duplicated.
• LaunchProgressMapper, ConnectAppLauncher, and LaunchOutcomeRouter have JVM unit-test coverage.

Risks to review:

• The multi-activity back-stack behavior (home ↔ job-status page ↔ opportunities list) is not exercised by the JVM test suite — it relies on the on-device verification above.
• userPressedOpportunityStatus is shared with the legacy LoginActivity launch path; it now keeps home alive and launches the job page on top for that path too.
• Removed ConnectAppUtils.getPasswordOverride/shouldOverridePassword after confirming no remaining source callers.

Automated test coverage

• LaunchProgressMapperTest covers the per-phase dialog state mapping (seating / signing-in / syncing, percent handling, message override).
• Existing ConnectAppLauncherTest and LaunchOutcomeRouterTest cover the launcher sequencing and outcome routing the controller delegates to.

[conroy-ricketts]

Suggested Review Order

• app/src/org/commcare/connect/ConnectAppLaunchController.kt — new shared launch orchestrator; the heart of the change
• app/src/org/commcare/connect/ConnectNavHelper.kt — adds the clearTop option used by the back-out path
• app/src/org/commcare/activities/HomeScreenBaseActivity.java — "View Job Status" + the Home launch intent; dead launchHome removed
• app/src/org/commcare/fragments/connect/ConnectJobsListsFragment.java — refactored onto the shared controller (boilerplate removed)
• app/src/org/commcare/fragments/connect/ConnectDeliveryProgressFragment.java — new caller of the controller
• app/src/org/commcare/fragments/connect/ConnectLearningProgressFragment.java — new caller of the controller
• app/src/org/commcare/connect/ConnectAppUtils.kt — dead-code removal
• app/unit-tests/src/org/commcare/connect/LaunchProgressMapperTest.kt — dialog-state mapping tests
• docs/commcare/login-engine.md — doc update for the launch/back-nav behavior
• RELEASES.md — QA notes

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR refactors the Connect app launch flow by extracting repeated launch orchestration logic from multiple fragments into a shared ConnectAppLaunchController. The controller manages login-progress dialogs, maps login phases to UI states via LaunchProgressMapper, routes outcomes through LaunchOutcomeRouter (home launch, token handling, seat recovery, legacy fallback), logs analytics, and handles back navigation. HomeScreenBaseActivity is updated to navigate to seated-app job pages from the Opportunity Status action and provides a new buildHomeLaunchIntent() public API. Three Connect-progress fragments (ConnectJobsListsFragment, ConnectDeliveryProgressFragment, ConnectLearningProgressFragment) migrate from inline launch logic to controller delegation, removing ~150 lines of redundant code. Navigation utilities are enhanced (clearTop flag support) and unused password helpers are removed. Tests verify the mapper behavior; documentation describes the new flow and back-navigation semantics.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~75 minutes

Suggested labels

skip-integration-tests

Suggested reviewers

• OrangeAndGreen
• shubham1g5

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 2.63% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'CCCT-2440 Connect App Launch For Remaining Pages And Back Navigation' clearly summarizes the main change: extending silent app launch and standardizing back navigation across Connect launch surfaces.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description check	✅ Passed	The PR description is comprehensive and covers all required template sections: Product Description details user-facing changes, Technical Summary provides rationale and design decisions with ticket link, and Safety Assurance addresses testing, confidence, and known risks.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch CCCT-2440-login-silent-launch-path-for-remaining-connect-pages

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@app/src/org/commcare/activities/HomeScreenBaseActivity.java`:
- Around line 589-596: In userPressedOpportunityStatus() in
HomeScreenBaseActivity, handle the null case from
ConnectJobHelper.INSTANCE.getJobForSeatedApp(this) by adding user feedback
and/or logging: if job is null, call Android Toast (or Snackbar) to inform the
user (e.g., "No active job found") and add a process or Android log entry (Log.w
or your logger) noting that getJobForSeatedApp returned null; retain the
existing call to ConnectNavHelper.INSTANCE.goToActiveInfoForJob(this, job, true)
when job is non-null.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: c93923c9-e88c-4f39-907f-e8e2e6d2f5c3

📥 Commits

Reviewing files that changed from the base of the PR and between aa9285c and ee1338f.

📒 Files selected for processing (10)

• RELEASES.md
• app/src/org/commcare/activities/HomeScreenBaseActivity.java
• app/src/org/commcare/connect/ConnectAppLaunchController.kt
• app/src/org/commcare/connect/ConnectAppUtils.kt
• app/src/org/commcare/connect/ConnectNavHelper.kt
• app/src/org/commcare/fragments/connect/ConnectDeliveryProgressFragment.java
• app/src/org/commcare/fragments/connect/ConnectJobsListsFragment.java
• app/src/org/commcare/fragments/connect/ConnectLearningProgressFragment.java
• app/unit-tests/src/org/commcare/connect/LaunchProgressMapperTest.kt
• docs/commcare/login-engine.md

💤 Files with no reviewable changes (1)

• app/src/org/commcare/connect/ConnectAppUtils.kt

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 25.62%. Comparing base (502c326) to head (983d87d).

Additional details and impacted files

@@                              Coverage Diff                              @@
##             CCCT-2439-connect-login-silent-launch-path    #3756   +/-   ##
=============================================================================
  Coverage                                         25.61%   25.62%           
  Complexity                                         4390     4390           
=============================================================================
  Files                                               953      954    +1     
  Lines                                             57779    57806   +27     
  Branches                                           6915     6921    +6     
=============================================================================
+ Hits                                              14799    14811   +12     
- Misses                                            41152    41167   +15     
  Partials                                           1828     1828           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.