ADFA-4900: wizard maps drive a per-layer install via local_vars + runrole

Wire the wizard maps Choose selection through to a real install using the existing
module-queue engine instead of the mock. MapsChooseFragment now carries the machine
level keys (base/satellite/terrain/search; null = off) through Confirm to Preparing;
Preparing starts the install (a module queue of {maps} plus the selection) and follows
the real ModuleQueueRepository state. InstallService, for the maps module, writes the
full maps_* var set to local_vars from the selection (vector quality; satellite/terrain
zoom or none; search engine + static db; region downloader; ne6; preset FQRs) via
sed-delete + echo (append-if-missing), validated against an allowlist, then runs
runrole maps under the shared success/failure verdict + revert-on-fail + progress.

Mapping confirmed against roles/maps tasks/install_frontend.yml.

Author: luisguzman-adfa

controller/app/src/main/java/org/iiab/controller/install/presentation/InstallService.java

@@ -87,6 +87,15 @@ public final class InstallService extends Service {
     public static final String MODE_INSTALL = "install";
     public static final String MODE_RESET = "reset";
 
+    // ADFA-4900: per-layer maps config carried with a module queue of {"maps"}. When present, the
+    // "maps" module writes the full maps_* var set to local_vars (from the wizard selection) before
+    // runrole, instead of the generic <key>_install/_enabled echo. Values are validated against a
+    // fixed allowlist before interpolation (D2).
+    public static final String EXTRA_MAPS_VECTOR = "mapsVector";   // nat-z8 | osm-z11 | osm-z14
+    public static final String EXTRA_MAPS_SAT = "mapsSat";         // 7|9|11|13 | none
+    public static final String EXTRA_MAPS_TERRAIN = "mapsTerrain"; // 7|8|9|10 | none
+    public static final String EXTRA_MAPS_SEARCH = "mapsSearch";   // boolean: static pop-1k-cities on/off
+
     private PowerManager.WakeLock wakeLock;
     private WifiManager.WifiLock wifiLock;
 
@@ -113,6 +122,17 @@ public final class InstallService extends Service {
     private java.util.Deque<String> moduleQueue;
     private java.util.List<String> failedModules;
 
+    // ADFA-4900: wizard maps per-layer config (only set when the queue is {"maps"} from the wizard).
+    private boolean hasMapsConfig;
+    private String mapsVector, mapsSat, mapsTerrain;
+    private boolean mapsSearchOn;
+    private static final java.util.Set<String> MAPS_VECTOR_OK =
+            new java.util.HashSet<>(java.util.Arrays.asList("nat-z8", "osm-z11", "osm-z14"));
+    private static final java.util.Set<String> MAPS_SAT_OK =
+            new java.util.HashSet<>(java.util.Arrays.asList("none", "7", "9", "11", "13"));
+    private static final java.util.Set<String> MAPS_TERRAIN_OK =
+            new java.util.HashSet<>(java.util.Arrays.asList("none", "7", "8", "9", "10"));
+
     private File iiabRootDir;     // filesDir/rootfs
     private File debianRootfs;    // filesDir/rootfs/installed-rootfs/iiab
 
@@ -156,6 +176,13 @@ public int onStartCommand(Intent intent, int flags, int startId) {
             }
             failedModules = new java.util.ArrayList<>();
 
+            // ADFA-4900: pick up the wizard maps per-layer selection, if any.
+            mapsVector = intent.getStringExtra(EXTRA_MAPS_VECTOR);
+            mapsSat = intent.getStringExtra(EXTRA_MAPS_SAT);
+            mapsTerrain = intent.getStringExtra(EXTRA_MAPS_TERRAIN);
+            mapsSearchOn = intent.getBooleanExtra(EXTRA_MAPS_SEARCH, false);
+            hasMapsConfig = mapsVector != null && moduleQueue.contains("maps");
+
             startForeground(NOTIFICATION_ID, buildNotification(getString(R.string.install_busy_modules)));
             acquireHardwareLocks();
             persistQueue();
@@ -658,7 +685,11 @@ private void installNextModule() {
             return;
         }
 
-        String installCmd = "sed -i -E '/^[[:space:]]*" + nextModule + "_(install|enabled)[[:space:]]*:/d' /etc/iiab/local_vars.yml && " +
+        // ADFA-4900: for the wizard maps flow, write the full per-layer maps_* var set before
+        // runrole (the generic <key>_install/_enabled echo can't express quality/off/search).
+        final String installCmd = ("maps".equals(nextModule) && hasMapsConfig)
+                ? mapsInstallCmd()
+                : "sed -i -E '/^[[:space:]]*" + nextModule + "_(install|enabled)[[:space:]]*:/d' /etc/iiab/local_vars.yml && " +
                 "echo '" + nextModule + "_install: True' >> /etc/iiab/local_vars.yml && " +
                 "echo '" + nextModule + "_enabled: True' >> /etc/iiab/local_vars.yml && " +
                 "cd /opt/iiab/iiab && ./runrole " + roleName;
@@ -717,6 +748,37 @@ private void revertModuleInLocalVars(String module, Runnable then) {
         });
     }
 
+    /**
+     * ADFA-4900: build the maps runrole command from the wizard's per-layer selection. Translates
+     * the selection into the maps role's local_vars (roles/maps/tasks/install_frontend.yml):
+     * satellite/terrain "none" turns the layer off; search maps to maps_search_engine +
+     * maps_search_static_db. Every var the role's iiab.ini step references is written so the play
+     * never hits an undefined var. Values are validated against a fixed allowlist (D2); anything
+     * unexpected falls back to a safe default. Uses sed-delete + echo (append-if-missing).
+     */
+    private String mapsInstallCmd() {
+        final String lv = "/etc/iiab/local_vars.yml";
+        String vq = MAPS_VECTOR_OK.contains(mapsVector) ? mapsVector : "osm-z11";
+        String sat = MAPS_SAT_OK.contains(mapsSat) ? mapsSat : "none";
+        String ter = MAPS_TERRAIN_OK.contains(mapsTerrain) ? mapsTerrain : "none";
+        String engine = mapsSearchOn ? "static" : "";
+        return "sed -i -E '/^[[:space:]]*maps_(install|enabled|region_downloader|vector_quality|" +
+                "satellite_zoom|terrain_zoom|search_engine|search_static_db|search_nominatim_db|" +
+                "ne6_zoom|preset_full_quality_regions)[[:space:]]*:/d' " + lv +
+                " && echo 'maps_install: True' >> " + lv +
+                " && echo 'maps_enabled: True' >> " + lv +
+                " && echo 'maps_region_downloader: True' >> " + lv +
+                " && echo 'maps_vector_quality: " + vq + "' >> " + lv +
+                " && echo 'maps_satellite_zoom: " + sat + "' >> " + lv +
+                " && echo 'maps_terrain_zoom: " + ter + "' >> " + lv +
+                " && echo 'maps_search_engine: \"" + engine + "\"' >> " + lv +
+                " && echo 'maps_search_static_db: pop-1k-cities' >> " + lv +
+                " && echo 'maps_search_nominatim_db: basic' >> " + lv +
+                " && echo 'maps_ne6_zoom: full' >> " + lv +
+                " && echo 'maps_preset_full_quality_regions: []' >> " + lv +
+                " && cd /opt/iiab/iiab && ./runrole maps";
+    }
+
     private void finishModuleQueue() {
         if (finished) return;
         finished = true;

controller/app/src/main/java/org/iiab/controller/redesign/MapsChooseFragment.java

@@ -118,12 +118,16 @@ public View onCreateView(@NonNull LayoutInflater inflater, @Nullable ViewGroup c
                 String[] names = new String[GROUPS.length];
                 String[] opts = new String[GROUPS.length];
                 long[] mb = new long[GROUPS.length];
+                // ADFA-4900: carry the machine level keys (null = "off") so the install can write
+                // local_vars — aligned to GROUPS order [base, satellite, terrain, search].
+                String[] levels = new String[GROUPS.length];
                 for (int gi = 0; gi < GROUPS.length; gi++) {
                     names[gi] = getString(GROUPS[gi].label);
                     opts[gi] = getString(GROUPS[gi].opts[selectedIdx[gi]].label);
                     mb[gi] = selectedMb[gi];
+                    levels[gi] = GROUPS[gi].opts[selectedIdx[gi]].level;
                 }
-                ((SetupLibraryActivity) getActivity()).openMapsConfirm(names, opts, mb);
+                ((SetupLibraryActivity) getActivity()).openMapsConfirm(names, opts, mb, levels);
             }
         });
 

controller/app/src/main/java/org/iiab/controller/redesign/MapsConfirmFragment.java

@@ -31,14 +31,15 @@
 
 public class MapsConfirmFragment extends Fragment {
 
-    private static final String ARG_NAMES = "names", ARG_OPTS = "opts", ARG_MB = "mb";
+    private static final String ARG_NAMES = "names", ARG_OPTS = "opts", ARG_MB = "mb", ARG_LEVELS = "levels";
 
-    public static MapsConfirmFragment newInstance(String[] names, String[] opts, long[] mb) {
+    public static MapsConfirmFragment newInstance(String[] names, String[] opts, long[] mb, String[] levels) {
         MapsConfirmFragment f = new MapsConfirmFragment();
         Bundle b = new Bundle();
         b.putStringArray(ARG_NAMES, names);
         b.putStringArray(ARG_OPTS, opts);
         b.putLongArray(ARG_MB, mb);
+        b.putStringArray(ARG_LEVELS, levels);   // ADFA-4900: per-layer machine keys (null = off)
         f.setArguments(b);
         return f;
     }
@@ -72,11 +73,13 @@ public View onCreateView(@NonNull LayoutInflater inflater, @Nullable ViewGroup c
         }
         box.addView(row(getString(R.string.k2go_maps_total), "", fmt(total), true));
 
+        final String[] levels = a != null ? a.getStringArray(ARG_LEVELS) : null;
+
         Button start = root.findViewById(R.id.k2go_start_btn);
         start.setText(getString(R.string.k2go_maps_start_building, fmt(total)));
         start.setOnClickListener(v -> {
             if (getActivity() instanceof SetupLibraryActivity) {
-                ((SetupLibraryActivity) getActivity()).openMapsPreparing();
+                ((SetupLibraryActivity) getActivity()).openMapsPreparing(levels);
             }
         });
 

controller/app/src/main/java/org/iiab/controller/redesign/MapsPreparingFragment.java

@@ -3,19 +3,17 @@
  * Name        : MapsPreparingFragment.java
  * Author      : AppDevForAll
  * Copyright   : Copyright (c) 2026 AppDevForAll
- * Description : ADFA-4848 (slice 3). Maps Preparing. A CONTAINED placeholder spinner
- *               (independent of the boot/close Lottie) plus a single status line that
- *               mirrors what the background process is doing, like the boot screen shows the
- *               current service. No invented progress bar. The status text is MOCK for now
- *               (cycles the phases); the REST/Ansible backend feeds the real output later.
- *               "Run in background" leaves it running and returns to the Get More hub.
+ * Description : ADFA-4848 (slice 3) / ADFA-4900. Maps Preparing. A contained placeholder
+ *               spinner plus a single status line. ADFA-4900: this now drives the REAL install
+ *               — on first entry it starts the maps runrole through the module-queue engine
+ *               (InstallService) with the per-layer selection, and the status line follows the
+ *               real queue state (ModuleQueueRepository), no longer a mock. "Run in background"
+ *               leaves it running and returns to the Get More hub.
  * ============================================================================
  */
 package org.iiab.controller.redesign;
 
 import android.os.Bundle;
-import android.os.Handler;
-import android.os.Looper;
 import android.view.LayoutInflater;
 import android.view.View;
 import android.view.ViewGroup;
@@ -26,21 +24,21 @@
 import androidx.fragment.app.Fragment;
 
 import org.iiab.controller.R;
+import org.iiab.controller.install.presentation.ModuleQueueRepository;
+import org.iiab.controller.install.presentation.ModuleQueueState;
 
 public class MapsPreparingFragment extends Fragment {
 
-    // Mock phase feed until the backend streams real process text.
-    private final int[] PHASES = {
-            R.string.k2go_maps_phase_prepared,
-            R.string.k2go_maps_phase_downloading,
-            R.string.k2go_maps_phase_building,
-            R.string.k2go_maps_phase_finishing,
-            R.string.k2go_maps_phase_ready,
-    };
+    private static final String ARG_LEVELS = "levels";
+
+    public static MapsPreparingFragment newInstance(String[] levels) {
+        MapsPreparingFragment f = new MapsPreparingFragment();
+        Bundle b = new Bundle();
+        b.putStringArray(ARG_LEVELS, levels);
+        f.setArguments(b);
+        return f;
+    }
 
-    private final Handler main = new Handler(Looper.getMainLooper());
-    private Runnable tick;
-    private int step = 0;
     private TextView status;
 
     @Nullable
@@ -49,37 +47,37 @@ public View onCreateView(@NonNull LayoutInflater inflater, @Nullable ViewGroup c
         View root = inflater.inflate(R.layout.fragment_k2go_maps_preparing, container, false);
 
         status = root.findViewById(R.id.k2go_prep_status);
+        status.setText(getString(R.string.k2go_maps_phase_prepared));
 
         // Run in background -> back to the Get More hub (drops the whole Maps flow off the
-        // back stack), the build keeps going.
+        // back stack), the build keeps going in the foreground service.
         root.findViewById(R.id.k2go_prep_run_bg).setOnClickListener(v -> {
             if (getActivity() instanceof SetupLibraryActivity) {
                 ((SetupLibraryActivity) getActivity()).backToGetMoreHub();
             }
         });
 
-        startMock();
-        return root;
-    }
+        // Start the real install only on first entry (not on a config-change recreation, and not
+        // if a maps job is already running/done from this session).
+        String[] levels = getArguments() != null ? getArguments().getStringArray(ARG_LEVELS) : null;
+        if (s == null
+                && getActivity() instanceof SetupLibraryActivity
+                && !ModuleQueueRepository.get().isRunning()) {
+            ((SetupLibraryActivity) getActivity()).startMapsInstall(levels);
+        }
 
-    private void startMock() {
-        step = 0;
-        tick = new Runnable() {
-            @Override
-            public void run() {
-                status.setText(getString(PHASES[step]));
-                if (step < PHASES.length - 1) {
-                    step++;
-                    main.postDelayed(this, 1500);
-                }
+        // Follow the real queue state instead of a mock phase cycle.
+        ModuleQueueRepository.get().state().observe(getViewLifecycleOwner(), st -> {
+            if (st == null) return;
+            if (st.phase == ModuleQueueState.Phase.RUNNING) {
+                status.setText(getString(R.string.k2go_maps_phase_building));
+            } else if (st.phase == ModuleQueueState.Phase.DONE) {
+                status.setText(st.failedModules.isEmpty()
+                        ? getString(R.string.k2go_maps_phase_ready)
+                        : getString(R.string.k2go_maps_phase_failed));
             }
-        };
-        main.post(tick);
-    }
+        });
 
-    @Override
-    public void onDestroyView() {
-        if (tick != null) main.removeCallbacks(tick);
-        super.onDestroyView();
+        return root;
     }
 }

controller/app/src/main/java/org/iiab/controller/redesign/SetupLibraryActivity.java

@@ -243,23 +243,44 @@ public void openMapsChoose() {
                 .commit();
     }
 
-    /** ADFA-4848: Choose -> Confirm (breakdown + total + time warning). */
-    public void openMapsConfirm(String[] names, String[] opts, long[] mb) {
+    /** ADFA-4848: Choose -> Confirm (breakdown + total + time warning). ADFA-4900: also carries the
+     *  per-layer level keys (aligned to the Choose groups; null = off) so Preparing can install. */
+    public void openMapsConfirm(String[] names, String[] opts, long[] mb, String[] levels) {
         getSupportFragmentManager().beginTransaction()
-                .replace(R.id.k2go_setup_host, MapsConfirmFragment.newInstance(names, opts, mb))
+                .replace(R.id.k2go_setup_host, MapsConfirmFragment.newInstance(names, opts, mb, levels))
                 .addToBackStack("maps_confirm")
                 .commit();
     }
 
-    /** ADFA-4848: Confirm -> Preparing (contained placeholder animation + process status; mock
-     *  until the backend). */
-    public void openMapsPreparing() {
+    /** ADFA-4848: Confirm -> Preparing. ADFA-4900: Preparing drives the real install (runrole maps
+     *  via the module-queue engine) using the per-layer selection and shows real progress. */
+    public void openMapsPreparing(String[] levels) {
         getSupportFragmentManager().beginTransaction()
-                .replace(R.id.k2go_setup_host, new MapsPreparingFragment())
+                .replace(R.id.k2go_setup_host, MapsPreparingFragment.newInstance(levels))
                 .addToBackStack("maps_preparing")
                 .commit();
     }
 
+    /** ADFA-4900: start the maps install through the module-queue engine (a queue of {"maps"} plus
+     *  the per-layer selection). InstallService writes the full maps_* local_vars and runs runrole
+     *  with the shared success/failure verdict, revert-on-fail and observable progress. {@code levels}
+     *  is aligned to the Choose groups [base, satellite, terrain, search]; null = off. */
+    public void startMapsInstall(String[] levels) {
+        String base = levels != null && levels.length > 0 && levels[0] != null ? levels[0] : "osm-z11";
+        String sat = levels != null && levels.length > 1 && levels[1] != null ? levels[1] : "none";
+        String ter = levels != null && levels.length > 2 && levels[2] != null ? levels[2] : "none";
+        boolean search = levels != null && levels.length > 3 && levels[3] != null;
+        Intent i = new Intent(this, InstallService.class);
+        i.setAction(InstallService.ACTION_START_MODULES);
+        i.putExtra(InstallService.EXTRA_MODULES, new String[]{"maps"});
+        i.putExtra(InstallService.EXTRA_MAPS_VECTOR, base);
+        i.putExtra(InstallService.EXTRA_MAPS_SAT, sat);
+        i.putExtra(InstallService.EXTRA_MAPS_TERRAIN, ter);
+        i.putExtra(InstallService.EXTRA_MAPS_SEARCH, search);
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) startForegroundService(i);
+        else startService(i);
+    }
+
     /** ADFA-4848: "Run in background" from Preparing -> drop the whole Maps flow off the back
      *  stack and return to the Get More hub; the build keeps running. */
     public void backToGetMoreHub() {

controller/app/src/main/res/values/strings_k2go.xml

@@ -395,6 +395,7 @@
     <string name="k2go_maps_phase_building" translatable="false">Building the map tiles</string>
     <string name="k2go_maps_phase_finishing" translatable="false">Finishing up</string>
     <string name="k2go_maps_phase_ready" translatable="false">Ready</string>
+    <string name="k2go_maps_phase_failed" translatable="false">Couldn\'t build maps — check space and connection, then retry</string>
 
     <!-- ADFA-4849: Wikipedia & ZIM content (WIP; translate in a later l10n pass) -->
     <string name="k2go_zim_title" translatable="false">Wikipedia &amp; ZIM content</string>