ubuntu-based-kiosk

374 Commits 1 Branch 1 Tag

3 Commits

Include renames

Author	SHA1	Message	Date
Claude	1b16bcf3ee	Migrate CUPS Printing addon; restructure install.sh into Core Settings/Addons/Advanced; bump to v2.5.0 First Addon migrated: menus/addon_cups.sh (install, reconfigure for network access, complete uninstall/purge). Different risk profile from everything migrated so far - it genuinely mutates real system state (apt install/remove --purge, /etc/cups, ufw) at fixed paths CUPS itself doesn't let us relocate, unlike the systemd/cron/bin paths this project already controls via $SYSTEMD_DIR etc. Only the polkit rule's directory is parameterized ($POLKIT_DIR, lib/config.sh, since that one is ours to place); everything else gets full command-level `sudo` stubbing in every test - there is no scratch equivalent for a real apt-managed subsystem's own file layout. Also added $BUILD_USER (the admin account actually running the tool, as opposed to $KIOSK_USER) since CUPS needs to grant it lpadmin group membership. Restructured install.sh's top-level menu into Core Settings / Addons / Advanced (matching the legacy tool) instead of one flat list, now that Addons exists as its own category - cheap to do with one item in it, much more annoying to retrofit once the flat list has fifteen. Two bugs caught and fixed before they shipped: - A "wait for CUPS to start" retry loop used a bare `cmd1 && cmd2 && break` as its body while "simplifying" the legacy script's `if cmd1 && cmd2; then break; fi`. Being inside a loop doesn't protect a bare &&/\|\| list from set -e - only if/while/until conditions and the protected side of &&/\|\| do that - so the first command failing on an early iteration (near-certain right after a fresh install, before CUPS has actually started) would have crashed the entire session. Restored the `if` form; noted the lesson in the file's own header comment since it's a general trap, not CUPS-specific. - Resolved real uncertainty, rather than assuming: how far does run_menu's `handler \|\| true` guard (v2.1.0) actually protect? Wrote a minimal isolated test (a bare `false` three function calls deep, called via `outer \|\| true` at the top) and confirmed bash's errexit exemption for the left side of `\|\|` covers the entire evaluation, arbitrarily deep through function calls - not just the immediately invoked function. So the session-crash risk this project has been chasing since v2.1.0 is already covered end-to-end by that one fix. Per-statement guards (`\|\| true`, explicit `if`) still earn their keep for a different reason: without them a deep failure bubbles silently past the menu actually responsible for it to wherever the nearest `\|\| true` happens to sit, which can be several menu levels above where the user actually was - not a crash, but a confusing jump. Verified: - Full regression: re-ran every existing scratch-config/stub test suite after the lib/config.sh change (new $BUILD_USER/$POLKIT_DIR) and after the install.sh restructuring - all still clean. - New scratch/stub test for addon_cups.sh: full state-machine coverage (not installed -> decline -> install -> running -> reconfigure -> stopped -> start -> uninstall decline -> uninstall confirm -> not installed again) with every `sudo` call intercepted and only `rm` targeting the scratch $POLKIT_DIR ever actually executed; confirmed the polkit rule's content and that declining install makes zero sudo calls. Added both apt-failure paths (update fails, install fails) and confirmed the tool reports clearly and returns to the menu instead of dying, exercising the exact bug class just fixed. - End-to-end: ran the real install.sh as a genuine non-root, non- "kiosk" user through the full new three-level structure - Core Settings -> Sites -> back -> back, Addons -> CUPS -> declined install (using this container's real, unstubbed dpkg check, correctly reporting "not installed" and making no apt/systemctl calls) -> back -> back, Advanced -> Diagnostics -> System status -> back -> back -> Exit. Zero invalid-choice errors, clean exit code 0 throughout.	2026-08-18 19:10:43 +00:00
Claude	2375bf5eab	Migrate WiFi and Power/Display/Quiet Hours menus; bump to v2.3.0 By far the riskiest menus migrated so far. Both can affect real system state outside config.json in ways that are hard to reverse: WiFi rewrites live netplan config and, over SSH, can disconnect the very session configuring it; power scheduling can shut the physical machine down and wake it via RTC. - lib/config.sh: new $SYSTEMD_DIR/$CRON_D_DIR/$BIN_DIR/$NETPLAN_DIR, same `: "${VAR:=default}"` pattern as $KIOSK_DIR. Nothing under menus/ hardcodes /etc/systemd/system, /etc/cron.d, /usr/local/bin, or /etc/netplan directly, so every test in this change points them at scratch space instead of ever touching this sandbox's real systemd units, cron, or network config. - lib/menu.sh: ported get_ip_address (also fixing its "No IP" fallback, which never actually fired before - `hostname -I \| awk` always exits 0 even on empty output). - menus/wifi.sh: apply_wifi_config split out from wifi_menu specifically so tests can drive the netplan-writing logic without needing real scan hardware. Preserves the legacy netplan backup, 60s SSH watchdog, and restore-on-failure behavior exactly. - menus/power_schedule.sh: power schedule (+ RTC wake), display schedule, quiet hours, and an Electron reload timer (with its own nested run_menu, mirroring the legacy configured/not-configured dispatch), plus remove-all. Deliberately excludes the legacy dispatcher's "Test schedules & system" - a shared diagnostics submenu (audio/network/keyboard tests) that isn't specific to scheduling and belongs with a future Advanced/Diagnostics migration instead. Bugs found and fixed along the way, none papered over: - The legacy dispatcher refused to open "Configure power schedule" at all without RTC hardware, even though shutdown-only mode never needed RTC. Now always available. - None of the six HH:MM prompts across these menus (shutdown, wake, display off/on, quiet start/end, custom Electron reload time) were validated before - plain `read`, no format check. All now go through ask_time. - set -e safety (same class as the v2.1.0 run_menu fix), three more instances: `ls .yaml` when no netplan file exists still fails under pipefail even with stderr silenced (masked in practice by cloud-init usually leaving a file behind); the restore-and-reapply `netplan apply` after an initial failure was a bare unguarded statement; and `systemctl enable`/`start` after writing each of the four timer pairs was unguarded too - caught only by testing in an environment without a live systemd, but a real enable/start failure on actual hardware (bad unit, daemon-reload skipped, ...) would hit the exact same crash. Added a shared enable_and_start_timers() helper used at all four call sites; all now report a clear warning and return to the menu instead of taking the session down. Testing discipline for this round, given the risk: - No automated test calls the real netplan/nmcli/iw/wpa_cli/systemctl - confirmed no WiFi tools or `wl` interface exist in this sandbox, so wifi_menu's own tools-check safely short-circuits before touching anything; apply_wifi_config's actual YAML/backup/failure-recovery logic is tested with sudo/netplan/get_ip_address stubbed instead. - One stubbing pitfall caught and fixed in the test itself: `nohup sudo bash "$watchdog" ... &` execs nohup as a real external binary, which then execs the real sudo - a bash function stub named `sudo` does NOT intercept that, only stubbing `nohup` itself does. Verified via pgrep that no real watchdog process or `sleep 60` was ever spawned. - power_schedule.sh tested with SYSTEMD_DIR/CRON_D_DIR/BIN_DIR pointed at scratch dirs and only `sudo systemctl` stubbed (tee/rm/chmod/cp left real, since they only ever touch scratch paths): full lifecycle for all four schedule types plus remove-all, the RTC-available branch (including the wake-time-before-shutdown-time hour/day wraparound arithmetic) via a stubbed rtc_wake_available, and the new enable_and_start_timers failure path via a stub that fails `enable` specifically. - End-to-end: ran the real install.sh as a genuine non-root, non- "kiosk" user for both menus. WiFi correctly short-circuits on missing tools without crashing. Power/Display/Quiet Hours (SYSTEMD_DIR/ CRON_D_DIR/BIN_DIR redirected to scratch space) configured all four schedule types in sequence including the nested Electron Reload menu, survived four consecutive real "systemctl enable/start failed" warnings (this container has no live systemd) without the session dying, then removed everything - confirmed the scratch dirs ended up empty and config.json was never touched (correctly out of scope for this menu).	2026-08-18 18:28:49 +00:00
Claude	21a0768c8c	Add modular menu framework, migrate Sites & Page Timing onto it Start of pulling the menu system out of the 12k-line single-file installer so individual menus can change without risking the rest of the script (network, VNC, addons, etc). This is groundwork for the planned web-based management UI, which will share the same lib/config.sh read/write layer instead of duplicating it. - lib/menu.sh: generic numbered-menu framework (auto-numbered entries, "0" always exits/returns) plus the validated input helpers menus need. - lib/config.sh: single load/save for config.json. Fixes a latent bug where the old Sites menu wrote config.json without first loading swipe/navigation/lockout settings, silently resetting them to defaults on save. - menus/sites.sh: Sites & Page Timing fully migrated - add/edit/delete/ reorder pages, set duration (auto-rotate/manual/hidden) and home page. Also fixes an off-by-one in the ported reorder logic (moving an item landed one slot short of the requested position) caught by testing. - install.sh: new entry point for managing an already-installed kiosk via `git clone` + `./install.sh`, wired to the Sites menu. Does not yet replace first-time provisioning, which still uses the existing single-file installer. All new site CRUD/reorder/home-page paths were exercised against a scratch config.json (add with/without basic auth, edit duration, set home + timeout, 2- and 3-item reorders in both directions, delete) to confirm the resulting config.json matches expectations.	2026-08-18 15:26:16 +00:00

Author

SHA1

Message

Date

Claude

1b16bcf3ee

Migrate CUPS Printing addon; restructure install.sh into Core Settings/Addons/Advanced; bump to v2.5.0

First Addon migrated: menus/addon_cups.sh (install, reconfigure for
network access, complete uninstall/purge). Different risk profile from
everything migrated so far - it genuinely mutates real system state
(apt install/remove --purge, /etc/cups, ufw) at fixed paths CUPS itself
doesn't let us relocate, unlike the systemd/cron/bin paths this project
already controls via $SYSTEMD_DIR etc. Only the polkit rule's directory
is parameterized ($POLKIT_DIR, lib/config.sh, since that one is ours to
place); everything else gets full command-level `sudo` stubbing in
every test - there is no scratch equivalent for a real apt-managed
subsystem's own file layout. Also added $BUILD_USER (the admin account
actually running the tool, as opposed to $KIOSK_USER) since CUPS needs
to grant it lpadmin group membership.

Restructured install.sh's top-level menu into Core Settings / Addons /
Advanced (matching the legacy tool) instead of one flat list, now that
Addons exists as its own category - cheap to do with one item in it,
much more annoying to retrofit once the flat list has fifteen.

Two bugs caught and fixed before they shipped:

- A "wait for CUPS to start" retry loop used a bare `cmd1 && cmd2 &&
  break` as its body while "simplifying" the legacy script's `if cmd1
  && cmd2; then break; fi`. Being inside a loop doesn't protect a bare
  &&/|| list from set -e - only if/while/until conditions and the
  protected side of &&/|| do that - so the first command failing on an
  early iteration (near-certain right after a fresh install, before
  CUPS has actually started) would have crashed the entire session.
  Restored the `if` form; noted the lesson in the file's own header
  comment since it's a general trap, not CUPS-specific.

- Resolved real uncertainty, rather than assuming: how far does
  run_menu's `handler || true` guard (v2.1.0) actually protect? Wrote a
  minimal isolated test (a bare `false` three function calls deep,
  called via `outer || true` at the top) and confirmed bash's errexit
  exemption for the left side of `||` covers the *entire* evaluation,
  arbitrarily deep through function calls - not just the immediately
  invoked function. So the session-crash risk this project has been
  chasing since v2.1.0 is already covered end-to-end by that one fix.
  Per-statement guards (`|| true`, explicit `if`) still earn their keep
  for a different reason: without them a deep failure bubbles silently
  past the menu actually responsible for it to wherever the nearest
  `|| true` happens to sit, which can be several menu levels above
  where the user actually was - not a crash, but a confusing jump.

Verified:
- Full regression: re-ran every existing scratch-config/stub test suite
  after the lib/config.sh change (new $BUILD_USER/$POLKIT_DIR) and
  after the install.sh restructuring - all still clean.
- New scratch/stub test for addon_cups.sh: full state-machine coverage
  (not installed -> decline -> install -> running -> reconfigure ->
  stopped -> start -> uninstall decline -> uninstall confirm -> not
  installed again) with every `sudo` call intercepted and only `rm`
  targeting the scratch $POLKIT_DIR ever actually executed; confirmed
  the polkit rule's content and that declining install makes zero sudo
  calls. Added both apt-failure paths (update fails, install fails)
  and confirmed the tool reports clearly and returns to the menu
  instead of dying, exercising the exact bug class just fixed.
- End-to-end: ran the real install.sh as a genuine non-root, non-
  "kiosk" user through the full new three-level structure - Core
  Settings -> Sites -> back -> back, Addons -> CUPS -> declined install
  (using this container's real, unstubbed dpkg check, correctly
  reporting "not installed" and making no apt/systemctl calls) -> back
  -> back, Advanced -> Diagnostics -> System status -> back -> back ->
  Exit. Zero invalid-choice errors, clean exit code 0 throughout.

2026-08-18 19:10:43 +00:00

Claude

2375bf5eab

Migrate WiFi and Power/Display/Quiet Hours menus; bump to v2.3.0

By far the riskiest menus migrated so far. Both can affect real system
state outside config.json in ways that are hard to reverse: WiFi
rewrites live netplan config and, over SSH, can disconnect the very
session configuring it; power scheduling can shut the physical machine
down and wake it via RTC.

- lib/config.sh: new $SYSTEMD_DIR/$CRON_D_DIR/$BIN_DIR/$NETPLAN_DIR,
  same `: "${VAR:=default}"` pattern as $KIOSK_DIR. Nothing under
  menus/ hardcodes /etc/systemd/system, /etc/cron.d, /usr/local/bin, or
  /etc/netplan directly, so every test in this change points them at
  scratch space instead of ever touching this sandbox's real systemd
  units, cron, or network config.
- lib/menu.sh: ported get_ip_address (also fixing its "No IP" fallback,
  which never actually fired before - `hostname -I | awk` always exits
  0 even on empty output).
- menus/wifi.sh: apply_wifi_config split out from wifi_menu specifically
  so tests can drive the netplan-writing logic without needing real
  scan hardware. Preserves the legacy netplan backup, 60s SSH watchdog,
  and restore-on-failure behavior exactly.
- menus/power_schedule.sh: power schedule (+ RTC wake), display
  schedule, quiet hours, and an Electron reload timer (with its own
  nested run_menu, mirroring the legacy configured/not-configured
  dispatch), plus remove-all. Deliberately excludes the legacy
  dispatcher's "Test schedules & system" - a shared diagnostics submenu
  (audio/network/keyboard tests) that isn't specific to scheduling and
  belongs with a future Advanced/Diagnostics migration instead.

Bugs found and fixed along the way, none papered over:
- The legacy dispatcher refused to open "Configure power schedule" at
  all without RTC hardware, even though shutdown-only mode never needed
  RTC. Now always available.
- None of the six HH:MM prompts across these menus (shutdown, wake,
  display off/on, quiet start/end, custom Electron reload time) were
  validated before - plain `read`, no format check. All now go through
  ask_time.
- set -e safety (same class as the v2.1.0 run_menu fix), three more
  instances: `ls *.yaml` when no netplan file exists still fails under
  pipefail even with stderr silenced (masked in practice by cloud-init
  usually leaving a file behind); the restore-and-reapply `netplan
  apply` after an initial failure was a bare unguarded statement; and
  `systemctl enable`/`start` after writing each of the four timer pairs
  was unguarded too - caught only by testing in an environment without
  a live systemd, but a real enable/start failure on actual hardware
  (bad unit, daemon-reload skipped, ...) would hit the exact same crash.
  Added a shared enable_and_start_timers() helper used at all four call
  sites; all now report a clear warning and return to the menu instead
  of taking the session down.

Testing discipline for this round, given the risk:
- No automated test calls the real netplan/nmcli/iw/wpa_cli/systemctl -
  confirmed no WiFi tools or `wl*` interface exist in this sandbox, so
  wifi_menu's own tools-check safely short-circuits before touching
  anything; apply_wifi_config's actual YAML/backup/failure-recovery
  logic is tested with sudo/netplan/get_ip_address stubbed instead.
- One stubbing pitfall caught and fixed in the test itself: `nohup sudo
  bash "$watchdog" ... &` execs nohup as a real external binary, which
  then execs the real sudo - a bash function stub named `sudo` does NOT
  intercept that, only stubbing `nohup` itself does. Verified via pgrep
  that no real watchdog process or `sleep 60` was ever spawned.
- power_schedule.sh tested with SYSTEMD_DIR/CRON_D_DIR/BIN_DIR pointed
  at scratch dirs and only `sudo systemctl` stubbed (tee/rm/chmod/cp
  left real, since they only ever touch scratch paths): full lifecycle
  for all four schedule types plus remove-all, the RTC-available branch
  (including the wake-time-before-shutdown-time hour/day wraparound
  arithmetic) via a stubbed rtc_wake_available, and the new
  enable_and_start_timers failure path via a stub that fails `enable`
  specifically.
- End-to-end: ran the real install.sh as a genuine non-root, non-
  "kiosk" user for both menus. WiFi correctly short-circuits on missing
  tools without crashing. Power/Display/Quiet Hours (SYSTEMD_DIR/
  CRON_D_DIR/BIN_DIR redirected to scratch space) configured all four
  schedule types in sequence including the nested Electron Reload menu,
  survived four consecutive real "systemctl enable/start failed"
  warnings (this container has no live systemd) without the session
  dying, then removed everything - confirmed the scratch dirs ended up
  empty and config.json was never touched (correctly out of scope for
  this menu).

2026-08-18 18:28:49 +00:00

Claude

21a0768c8c

Add modular menu framework, migrate Sites & Page Timing onto it

Start of pulling the menu system out of the 12k-line single-file
installer so individual menus can change without risking the rest of
the script (network, VNC, addons, etc). This is groundwork for the
planned web-based management UI, which will share the same lib/config.sh
read/write layer instead of duplicating it.

- lib/menu.sh: generic numbered-menu framework (auto-numbered entries,
  "0" always exits/returns) plus the validated input helpers menus need.
- lib/config.sh: single load/save for config.json. Fixes a latent bug
  where the old Sites menu wrote config.json without first loading
  swipe/navigation/lockout settings, silently resetting them to
  defaults on save.
- menus/sites.sh: Sites & Page Timing fully migrated - add/edit/delete/
  reorder pages, set duration (auto-rotate/manual/hidden) and home page.
  Also fixes an off-by-one in the ported reorder logic (moving an item
  landed one slot short of the requested position) caught by testing.
- install.sh: new entry point for managing an already-installed kiosk
  via `git clone` + `./install.sh`, wired to the Sites menu. Does not
  yet replace first-time provisioning, which still uses the existing
  single-file installer.

All new site CRUD/reorder/home-page paths were exercised against a
scratch config.json (add with/without basic auth, edit duration, set
home + timeout, 2- and 3-item reorders in both directions, delete) to
confirm the resulting config.json matches expectations.

2026-08-18 15:26:16 +00:00