Add in-app regeneration of offline.pmtiles and terrain.pmtiles

A logged-in user can now trigger, from a new "Offline data" sidebar
panel, what was previously a fully manual go-pmtiles workflow
(docs/development.adoc): regenerate either file for the current map
viewport, no area-picker (same "visible area is the area" convention
the Overpass POI plugin already uses).

- lib/maptool/pmtiles_builder.rb: two independent background jobs
  (Thread + Mutex-guarded status Hash, same shape as app.rb's own GNSS
  poller), each writing to a .tmp path and atomically renaming into
  place so a build never serves a partially-written file mid-run.
  offline.pmtiles is a single `pmtiles extract` against Protomaps'
  public daily basemap build (byte-range extraction, not a full
  ~120GB download). terrain.pmtiles has no equivalent public
  Terrarium-encoded archive to extract from, so it fetches individual
  Terrarium tiles itself, packs them into an intermediate MBTiles
  (new sqlite3 gem), then the same `pmtiles convert`.
- 4 new app.rb routes (POST .../build, GET .../build-status) plus
  size/mtime added to the existing availability endpoints.
- public/js/offline_data.js: new sidebar panel, polling build-status
  the same self-rescheduling-setTimeout shape livetrack.js already
  uses for its own refresh loop.
- Both network-heavy pieces (the Protomaps build index, per-tile
  fetches) are injectable, so test/test_pmtiles_builder.rb exercises
  the actual build pipeline against a fake `pmtiles` binary without
  hitting a real network, matching this suite's existing
  keep-it-offline convention for external services.

test/test_app.rb

@@ -70,6 +70,8 @@ class AppTest < Minitest::Test
     assert_equal 401, request.delete("/api/gpx/folder/x").status
     assert_equal 401, request.post("/api/gpx/move").status
     assert_equal 401, request.post("/api/plugins/test-plugin/run").status
+    assert_equal 401, request.post("/api/offline-tiles/build").status
+    assert_equal 401, request.post("/api/terrain-tiles/build").status
   end
 
   # --- GPX/FIT upload and the tree ---
@@ -347,6 +349,47 @@ class AppTest < Minitest::Test
     assert_equal 502, response.status
   end
 
+  # --- pmtiles regeneration ---
+  #
+  # The full build (network + go-pmtiles) is covered in isolation, with
+  # fakes injected, by test_pmtiles_builder.rb — same "keep this offline"
+  # reasoning as the rest of this file. What's route-specific and worth
+  # covering here is the bbox validation and the 409-while-running guard,
+  # neither of which needs a real build to actually run.
+
+  def test_offline_tiles_build_status_defaults_to_idle
+    assert_equal({ "state" => "idle" }, json_body(request.get("/api/offline-tiles/build-status")))
+    assert_equal({ "state" => "idle" }, json_body(request.get("/api/terrain-tiles/build-status")))
+  end
+
+  def test_offline_tiles_build_requires_a_bbox
+    response = request.post("/api/offline-tiles/build", **logged_in_env)
+    assert_equal 400, response.status
+  end
+
+  def test_terrain_tiles_build_requires_a_bbox
+    response = request.post("/api/terrain-tiles/build", **logged_in_env)
+    assert_equal 400, response.status
+  end
+
+  # fetch_build_url blocks on a Queue, called directly (not through the
+  # route, which has no way to inject a fake) so the build is
+  # deterministically still "running" when the route call below happens.
+  def test_offline_tiles_build_is_409_when_one_is_already_running
+    gate = Queue.new
+    thread = Maptool::PmtilesBuilder.build_offline([1, 2, 3, 4], data_dir: Maptool::App::DATA_DIR, fetch_build_url: -> { gate.pop })
+
+    response = request.post(
+      "/api/offline-tiles/build",
+      params: { south: "1", west: "2", north: "3", east: "4" },
+      **logged_in_env,
+    )
+    assert_equal 409, response.status
+  ensure
+    gate.push("unused")
+    thread&.join
+  end
+
   # --- LiveTrack webhook ---
 
   def test_livetrack_webhook_requires_the_configured_secret

test/test_helper.rb

@@ -66,6 +66,7 @@ module AppTestHelper
   def teardown
     FileUtils.rm_rf(Dir.glob(File.join(Maptool::App::DATA_DIR, "gpx", "*")))
     File.write(File.join(Maptool::App::DATA_DIR, "livetrack.json"), "[]")
+    Maptool::PmtilesBuilder.reset!
     super
   end
 

test/test_pmtiles_builder.rb

@@ -0,0 +1,130 @@
+require_relative "test_helper"
+require "maptool/pmtiles_builder"
+require "tmpdir"
+require "fileutils"
+
+# Network calls (the protomaps build index, individual Terrarium tile
+# fetches) are never exercised here — same "keep this offline/deterministic"
+# reasoning test_helper.rb already gives for /api/plugins staying off the
+# real Overpass API — build_offline/build_terrain take fetch_build_url/
+# fetch_tile precisely so tests can swap those out. A fake `pmtiles` CLI
+# (PMTILES_BIN) stands in for the real go-pmtiles binary.
+class PmtilesBuilderTest < Minitest::Test
+  def setup
+    @data_dir = Dir.mktmpdir("maptool-pmtiles-test-data")
+    @bin_dir = Dir.mktmpdir("maptool-pmtiles-test-bin")
+
+    # $3 is the output path either way: `extract SOURCE OUTPUT --bbox=...
+    # --maxzoom=...` and `convert INPUT OUTPUT` both put it 3rd, even though
+    # it's not the *last* arg in the extract case (the --flags follow it).
+    @pmtiles_ok = File.join(@bin_dir, "pmtiles-ok")
+    File.write(@pmtiles_ok, "#!/bin/sh\necho fake > \"$3\"\n")
+    File.chmod(0o755, @pmtiles_ok)
+
+    @pmtiles_fail = File.join(@bin_dir, "pmtiles-fail")
+    File.write(@pmtiles_fail, "#!/bin/sh\necho 'boom' >&2\nexit 1\n")
+    File.chmod(0o755, @pmtiles_fail)
+
+    @original_pmtiles_bin = ENV["PMTILES_BIN"]
+    Maptool::PmtilesBuilder.reset!
+  end
+
+  def teardown
+    FileUtils.remove_entry(@data_dir)
+    FileUtils.remove_entry(@bin_dir)
+    ENV["PMTILES_BIN"] = @original_pmtiles_bin
+    Maptool::PmtilesBuilder.reset!
+  end
+
+  def test_offline_and_terrain_status_start_idle
+    assert_equal({ state: "idle" }, Maptool::PmtilesBuilder.offline_status)
+    assert_equal({ state: "idle" }, Maptool::PmtilesBuilder.terrain_status)
+  end
+
+  def test_build_offline_writes_the_file_and_reports_done
+    ENV["PMTILES_BIN"] = @pmtiles_ok
+    thread = Maptool::PmtilesBuilder.build_offline(
+      [1, 2, 3, 4],
+      data_dir: @data_dir,
+      fetch_build_url: -> { "https://example.com/fake.pmtiles" },
+    )
+    thread.join
+
+    assert_path_exists File.join(@data_dir, "offline.pmtiles")
+    refute_path_exists File.join(@data_dir, "offline.pmtiles.tmp")
+    assert_equal "done", Maptool::PmtilesBuilder.offline_status[:state]
+  end
+
+  def test_build_offline_reports_an_error_status_on_non_zero_exit
+    ENV["PMTILES_BIN"] = @pmtiles_fail
+    thread = Maptool::PmtilesBuilder.build_offline(
+      [1, 2, 3, 4],
+      data_dir: @data_dir,
+      fetch_build_url: -> { "https://example.com/fake.pmtiles" },
+    )
+    thread.join
+
+    refute_path_exists File.join(@data_dir, "offline.pmtiles")
+    status = Maptool::PmtilesBuilder.offline_status
+    assert_equal "error", status[:state]
+    assert_match(/exited with status/, status[:message])
+  end
+
+  def test_build_offline_reports_a_clear_error_when_the_binary_is_missing
+    ENV["PMTILES_BIN"] = File.join(@bin_dir, "does-not-exist")
+    thread = Maptool::PmtilesBuilder.build_offline(
+      [1, 2, 3, 4],
+      data_dir: @data_dir,
+      fetch_build_url: -> { "https://example.com/fake.pmtiles" },
+    )
+    thread.join
+
+    status = Maptool::PmtilesBuilder.offline_status
+    assert_equal "error", status[:state]
+    assert_match(/go-pmtiles installed/, status[:message])
+  end
+
+  # fetch_build_url blocks on a Queue so the build is deterministically
+  # still "running" when the second call happens, rather than racing a real
+  # one to see which state wins.
+  def test_build_offline_raises_when_one_is_already_running
+    ENV["PMTILES_BIN"] = @pmtiles_ok
+    gate = Queue.new
+    thread = Maptool::PmtilesBuilder.build_offline([1, 2, 3, 4], data_dir: @data_dir, fetch_build_url: -> { gate.pop })
+
+    assert_raises(Maptool::PmtilesBuilder::BuildError) do
+      Maptool::PmtilesBuilder.build_offline([1, 2, 3, 4], data_dir: @data_dir, fetch_build_url: -> { "unused" })
+    end
+  ensure
+    gate.push("https://example.com/fake.pmtiles")
+    thread&.join
+  end
+
+  # A tiny real-world bbox (a few blocks of central Bratislava) keeps the
+  # z0..15 tile_range small at every zoom level, so this stays fast even
+  # though it iterates all 16 levels.
+  def test_build_terrain_packs_fetched_tiles_and_converts
+    ENV["PMTILES_BIN"] = @pmtiles_ok
+    thread = Maptool::PmtilesBuilder.build_terrain(
+      [48.140, 17.100, 48.141, 17.101],
+      data_dir: @data_dir,
+      fetch_tile: ->(_z, _x, _y) { "not a real png, write_terrarium_mbtiles just stores opaque bytes" },
+    )
+    thread.join
+
+    assert_path_exists File.join(@data_dir, "terrain.pmtiles")
+    assert_equal "done", Maptool::PmtilesBuilder.terrain_status[:state]
+  end
+
+  def test_build_terrain_still_succeeds_when_some_tiles_are_missing
+    ENV["PMTILES_BIN"] = @pmtiles_ok
+    thread = Maptool::PmtilesBuilder.build_terrain(
+      [48.140, 17.100, 48.141, 17.101],
+      data_dir: @data_dir,
+      fetch_tile: ->(_z, _x, _y) { nil }, # every tile "missing" — should skip, not fail, the same way HillshadeControl's own source tolerates gaps
+    )
+    thread.join
+
+    assert_equal "done", Maptool::PmtilesBuilder.terrain_status[:state]
+  end
+end