From 88e9da8fe19787cdc6bf51d167cadbbfb69fa3d1 Mon Sep 17 00:00:00 2001 From: meowtypes Date: Thu, 28 May 2026 02:58:52 -0700 Subject: [PATCH 01/41] docs: add libadwaita migration spec and implementation plan --- .gitignore | 1 + .../plans/2026-05-28-libadwaita-migration.md | 1368 +++++++++++++++++ .../2026-05-28-libadwaita-migration-design.md | 215 +++ 3 files changed, 1584 insertions(+) create mode 100644 docs/superpowers/plans/2026-05-28-libadwaita-migration.md create mode 100644 docs/superpowers/specs/2026-05-28-libadwaita-migration-design.md diff --git a/.gitignore b/.gitignore index f038882..1d2a9a1 100644 --- a/.gitignore +++ b/.gitignore @@ -5,3 +5,4 @@ dist/ *.AppImage *.AppImage.sha256 tests/ +.superpowers/ diff --git a/docs/superpowers/plans/2026-05-28-libadwaita-migration.md b/docs/superpowers/plans/2026-05-28-libadwaita-migration.md new file mode 100644 index 0000000..3c27b8a --- /dev/null +++ b/docs/superpowers/plans/2026-05-28-libadwaita-migration.md @@ -0,0 +1,1368 @@ +# libadwaita UI Migration Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Migrate the Mount Manager GUI from plain GTK 4 widgets to libadwaita ≥ 1.5, splitting the UI code out of `mount_manager.py` into a new `mount_manager_ui.py` module. + +**Architecture:** In-place migration. `mount_manager.py` keeps data models, systemd/credentials plumbing, polkit handoff, and the `--helper` subprocess entry point. A new `mount_manager_ui.py` defines `Adw.Application`, `Adw.ApplicationWindow` (with `Adw.ToolbarView` + `Adw.ToastOverlay`), an `AddShareDialog(Adw.Dialog)`, an `Adw.AlertDialog`-based delete confirmation, and an `Adw.AboutDialog`. The custom `APP_CSS` and manual color-scheme detection are deleted in favor of `Adw.StyleManager`. + +**Tech Stack:** Python 3, PyGObject (`gi`), GTK 4, libadwaita ≥ 1.5, stdlib `unittest` for tests. + +**Spec reference:** `docs/superpowers/specs/2026-05-28-libadwaita-migration-design.md` + +## Testing strategy + +This project has no existing test suite. We add stdlib `unittest` tests for the **pure-Python helpers** introduced or touched by this plan (`_libadwaita_supports`, `mount_status_line`). For the GTK/Adw widget construction we use **manual verification on a Bazzite host** because headless widget-tree assertions add little value and would require introducing Xvfb/`gi` to CI for no gain. Each task that builds widgets includes a concrete manual-verification checklist; tasks that introduce a pure helper include a real unittest. + +**Test command** (used throughout): `python3 -m unittest discover -s tests -v` +**App run command** (used throughout): `python3 mount_manager.py` + +--- + +## File Structure + +After this plan is complete: + +- `mount_manager.py` — data models, systemd/creds plumbing, `--helper` subprocess, `_libadwaita_supports()`, `main()`. **No GUI code.** +- `mount_manager_ui.py` *(new)* — `gi.require_version("Adw","1")` at module level. Defines `ensure_libadwaita_supported`, `apply_style_manager`, `mount_status_line`, `MainWindow(Adw.ApplicationWindow)`, `AddShareDialog(Adw.Dialog)`, `DeleteAlertDialog` (factory returning `Adw.AlertDialog`), `MountManagerApplication(Adw.Application)`, and `run_gui()`. +- `tests/` *(new)* — `__init__.py` (empty), `test_libadwaita_support.py`, `test_mount_status_line.py`. +- `packaging/build-appimage.sh` — installs `mount_manager_ui.py` alongside `mount_manager.py`. +- `README.md` — adds libadwaita requirement and updates manual-install commands. + +--- + +## Task 1: Test scaffolding + +**Files:** +- Create: `tests/__init__.py` +- Create: `tests/test_smoke.py` + +This task establishes the test harness so later tasks can add real tests. It includes a single trivial smoke test that imports `mount_manager` to confirm the harness works. + +- [ ] **Step 1: Create empty `tests/__init__.py`** + +```bash +mkdir -p tests +: > tests/__init__.py +``` + +- [ ] **Step 2: Create `tests/test_smoke.py`** + +```python +"""Smoke test ensuring the test harness can import the main module.""" + +import unittest + + +class ImportSmokeTest(unittest.TestCase): + def test_import_mount_manager(self) -> None: + import mount_manager # noqa: F401 + + self.assertTrue(hasattr(mount_manager, "main")) + + +if __name__ == "__main__": + unittest.main() +``` + +- [ ] **Step 3: Run the test** + +Run: `python3 -m unittest discover -s tests -v` +Expected output ends with `OK` and shows `test_import_mount_manager ... ok`. + +- [ ] **Step 4: Commit** + +```bash +git add tests/ +git commit -m "test: add unittest scaffolding with import smoke test" +``` + +--- + +## Task 2: `_libadwaita_supports()` version check helper + +**Files:** +- Modify: `mount_manager.py` (add helper near `MIN_SYSTEMD_VERSION`) +- Create: `tests/test_libadwaita_support.py` + +Adds a pure comparator usable without `gi` so it can be unit-tested directly. The actual `ensure_libadwaita_supported()` (which reads `Adw.MAJOR_VERSION`/`Adw.MINOR_VERSION`) lives in the UI module and calls this. + +- [ ] **Step 1: Write the failing test** + +Create `tests/test_libadwaita_support.py`: + +```python +"""Unit tests for the libadwaita version comparator.""" + +import unittest + +from mount_manager import _libadwaita_supports + + +class LibadwaitaSupportsTest(unittest.TestCase): + def test_minimum_supported_version(self) -> None: + self.assertTrue(_libadwaita_supports(1, 5)) + + def test_newer_minor_supported(self) -> None: + self.assertTrue(_libadwaita_supports(1, 7)) + + def test_newer_major_supported(self) -> None: + self.assertTrue(_libadwaita_supports(2, 0)) + + def test_older_minor_unsupported(self) -> None: + self.assertFalse(_libadwaita_supports(1, 4)) + + def test_older_major_unsupported(self) -> None: + self.assertFalse(_libadwaita_supports(0, 99)) + + +if __name__ == "__main__": + unittest.main() +``` + +- [ ] **Step 2: Run the test to confirm it fails** + +Run: `python3 -m unittest tests.test_libadwaita_support -v` +Expected: `ImportError: cannot import name '_libadwaita_supports' from 'mount_manager'` + +- [ ] **Step 3: Add the helper and a `MIN_LIBADWAITA_VERSION` constant** + +In `mount_manager.py`, locate the line `MIN_SYSTEMD_VERSION = 258` and insert immediately after it: + +```python +# Adw.Dialog and Adw.AlertDialog require libadwaita 1.5 or newer. +MIN_LIBADWAITA_VERSION: tuple[int, int] = (1, 5) + + +def _libadwaita_supports(major: int, minor: int) -> bool: + """Return True if the given libadwaita (major, minor) meets the app's minimum.""" + return (major, minor) >= MIN_LIBADWAITA_VERSION +``` + +- [ ] **Step 4: Run the test to confirm it passes** + +Run: `python3 -m unittest tests.test_libadwaita_support -v` +Expected: all five tests pass, output ends with `OK`. + +- [ ] **Step 5: Commit** + +```bash +git add mount_manager.py tests/test_libadwaita_support.py +git commit -m "feat: add libadwaita version comparator" +``` + +--- + +## Task 3: Extract UI to `mount_manager_ui.py` (pure refactor) + +**Files:** +- Create: `mount_manager_ui.py` +- Modify: `mount_manager.py` (lines ~1148–1682: remove `import_gtk`, `apply_theme`, `run_gui` body, all nested UI classes) + +This is a **pure refactor with no UI behavior change**. We move the existing GTK widgets verbatim into a new module so subsequent tasks operate on a smaller file. `APP_CSS` and `apply_theme` move with the GUI code (they will be deleted in Task 4). Constants needed by the UI (`APP_NAME`, `APP_ID`, `APP_DEVELOPERS`, `APP_WEBSITE`, `APP_ICON_NAME`, `COLOR_SCHEME_ENV`) are imported from `mount_manager`. + +- [ ] **Step 1: Create `mount_manager_ui.py` with the extracted code** + +Create `mount_manager_ui.py` with: + +```python +"""GTK 4 GUI for SMB Mount Manager. + +This module is imported lazily from ``mount_manager.run_gui``. Keeping it +separate from ``mount_manager.py`` lets the helper subprocess avoid importing +GTK when invoked with ``--helper``. +""" + +from __future__ import annotations + +import sys +from typing import Any + +import gi + +gi.require_version("Gdk", "4.0") +gi.require_version("Gtk", "4.0") +gi.require_version("Pango", "1.0") +from gi.repository import Gdk, Gio, Gtk, Pango # noqa: E402 + +from mount_manager import ( + APP_DEVELOPERS, + APP_ICON_NAME, + APP_ID, + APP_NAME, + APP_WEBSITE, + DisplayedMount, + ManagedMount, + MountManagerError, + SharePath, + check_smb_host_reachable, + detect_color_scheme, + load_displayed_mounts, + request_helper_create, + request_helper_delete, + request_helper_set_enabled, + request_helper_upgrade, + run_command, + validate_credentials, +) + + +APP_CSS = """ +# ... PASTE THE EXISTING APP_CSS STRING VERBATIM FROM mount_manager.py ... +""" + + +def apply_theme(Gtk: Any, Gdk: Any) -> None: + settings = Gtk.Settings.get_default() + if settings is not None: + settings.set_property( + "gtk-application-prefer-dark-theme", + detect_color_scheme() == "dark", + ) + + display = Gdk.Display.get_default() + if display is None: + return + + Gtk.Window.set_default_icon_name(APP_ICON_NAME) + + provider = Gtk.CssProvider() + provider.load_from_data(APP_CSS.encode("utf-8")) + Gtk.StyleContext.add_provider_for_display( + display, + provider, + Gtk.STYLE_PROVIDER_PRIORITY_APPLICATION, + ) + + +def run_gui() -> int: + if not Gtk.init_check(): + print( + "GTK could not connect to your graphical session. Run this from your " + "desktop session, not a plain TTY.", + file=sys.stderr, + ) + return 1 + if Gdk.Display.get_default() is None: + print( + "GTK did not provide a usable display. Run this from your desktop " + "session, not a plain TTY.", + file=sys.stderr, + ) + return 1 + apply_theme(Gtk, Gdk) + + # PASTE THE EXISTING NESTED CLASSES (AddShareWindow, MessageWindow, + # DeleteMountWindow, MainWindow, MountManagerApplication) VERBATIM HERE, + # AS NESTED CLASSES INSIDE run_gui — DO NOT REINDENT OR EDIT THEM. + + app = MountManagerApplication() + return app.run(sys.argv) +``` + +Copy the exact text of `APP_CSS` (currently `mount_manager.py` lines 53–122) into the placeholder. Copy the exact nested class definitions from `mount_manager.py` (currently lines 1200–1679) into the `run_gui` body in place of the placeholder comment — preserve indentation. + +- [ ] **Step 2: Trim `mount_manager.py`** + +In `mount_manager.py`: + +1. Delete the `APP_CSS = """..."""` block (currently lines 53–122). +2. Delete `import_gtk()` (currently lines 1148–1156). +3. Delete `apply_theme(Gtk, Gdk)` (currently lines 1159–1179). +4. Replace the entire body of `run_gui()` with: + +```python +def run_gui() -> int: + from mount_manager_ui import run_gui as _run_gui + + return _run_gui() +``` + +5. Leave the existing imports in `mount_manager.py` alone — leftover imports from removed code don't affect correctness and chasing them down here is risky. They can be cleaned up after the migration is verified. + +- [ ] **Step 3: Run the import smoke test** + +Run: `python3 -m unittest discover -s tests -v` +Expected: all tests pass (smoke + libadwaita comparator). `OK`. + +- [ ] **Step 4: Manual verification — app still works** + +Run: `python3 mount_manager.py` +Expected: +- Main window opens with the same look as before this task (custom CSS still active, GTK header bar, "ADD SHARE" button visible). +- Existing mounts are listed. +- Add Share → Cancel works. +- About menu entry opens the existing `Gtk.AboutDialog`. + +If anything is broken, fix the extraction (most likely cause: a missing import or a missed class reference between the nested classes). + +- [ ] **Step 5: Commit** + +```bash +git add mount_manager.py mount_manager_ui.py +git commit -m "refactor: split GUI code into mount_manager_ui module" +``` + +--- + +## Task 4: Adw application bootstrap, version check, StyleManager + +**Files:** +- Modify: `mount_manager_ui.py` + +We require libadwaita 1.5+, switch to `Adw.StyleManager`, and delete the custom CSS / theme code introduced by Task 3. + +- [ ] **Step 1: Add Adw imports and version-check function** + +At the top of `mount_manager_ui.py`, after `gi.require_version("Pango", "1.0")`, add: + +```python +gi.require_version("Adw", "1") +``` + +Update the `from gi.repository` line to include `Adw`: + +```python +from gi.repository import Adw, Gdk, Gio, Gtk, Pango # noqa: E402 +``` + +Add to the imports from `mount_manager`: + +```python + MIN_LIBADWAITA_VERSION, + _libadwaita_supports, +``` + +Below the imports add: + +```python +def ensure_libadwaita_supported() -> None: + """Print an error and raise SystemExit if libadwaita is too old.""" + if not _libadwaita_supports(Adw.MAJOR_VERSION, Adw.MINOR_VERSION): + required = ".".join(str(v) for v in MIN_LIBADWAITA_VERSION) + found = f"{Adw.MAJOR_VERSION}.{Adw.MINOR_VERSION}" + print( + f"libadwaita {found} found, but this app requires {required} or newer.", + file=sys.stderr, + ) + raise SystemExit(1) + + +def apply_style_manager() -> None: + """Hand color-scheme selection to libadwaita's system preference tracker.""" + Adw.StyleManager.get_default().set_color_scheme(Adw.ColorScheme.DEFAULT) + Gtk.Window.set_default_icon_name(APP_ICON_NAME) +``` + +- [ ] **Step 2: Delete `APP_CSS` and `apply_theme`** + +In `mount_manager_ui.py`, delete the whole `APP_CSS = """..."""` block and the `apply_theme(Gtk, Gdk)` function added during Task 3. + +- [ ] **Step 3: Replace the prelude of `run_gui`** + +Replace the existing `apply_theme(Gtk, Gdk)` call (and the `Gdk.Display.get_default()` check that came after `Gtk.init_check`) so the prelude reads: + +```python +def run_gui() -> int: + ensure_libadwaita_supported() + if not Gtk.init_check(): + print( + "GTK could not connect to your graphical session. Run this from your " + "desktop session, not a plain TTY.", + file=sys.stderr, + ) + return 1 + if Gdk.Display.get_default() is None: + print( + "GTK did not provide a usable display. Run this from your desktop " + "session, not a plain TTY.", + file=sys.stderr, + ) + return 1 + apply_style_manager() + + # ... existing nested classes unchanged for now ... +``` + +- [ ] **Step 4: Convert the Application class** + +Inside `run_gui()`, change the `MountManagerApplication` definition (currently `class MountManagerApplication(Gtk.Application):`) to: + +```python + class MountManagerApplication(Adw.Application): + def __init__(self) -> None: + super().__init__(application_id=APP_ID, flags=Gio.ApplicationFlags.DEFAULT_FLAGS) + + def do_activate(self) -> None: + window = self.props.active_window + if window is None: + window = MainWindow(self) + window.present() +``` + +The base class change is the only behavioral edit; `do_activate` is unchanged. + +- [ ] **Step 5: Manual verification** + +Run: `python3 mount_manager.py` +Expected: +- App still launches. +- Window still shows the same content as before (we have not yet changed `MainWindow`). +- Color scheme follows the system: switch GNOME's "Style" preference (Settings → Appearance) between Light and Dark; the window should follow without restart. +- No custom CSS — the window background and header bar may look slightly different from the pre-Adw look; that is expected. + +- [ ] **Step 6: Run unit tests** + +Run: `python3 -m unittest discover -s tests -v` +Expected: `OK`. + +- [ ] **Step 7: Commit** + +```bash +git add mount_manager.py mount_manager_ui.py +git commit -m "feat(ui): switch to Adw.Application and Adw.StyleManager" +``` + +--- + +## Task 5: Adw.ApplicationWindow + ToolbarView + HeaderBar + ToastOverlay + +**Files:** +- Modify: `mount_manager_ui.py` (the nested `MainWindow` class) + +Convert `MainWindow` to libadwaita's shell. The header bar gets an "Add Share" suggested-action button on the left and refresh + menu buttons on the right. A `Adw.ToastOverlay` is added around the content so later tasks can call `self.show_toast("…")`. The mount list rendering inside the window body is unchanged in this task (still `Gtk.ListBox` with `boxed-list`); Tasks 6–8 replace it. + +- [ ] **Step 1: Replace the `MainWindow` class header and constructor** + +Inside `run_gui()`, replace the existing `class MainWindow(Gtk.ApplicationWindow):` definition (constructor only — keep `refresh`, `row_for`, `show_add_dialog`, etc. unchanged for now) with: + +```python + class MainWindow(Adw.ApplicationWindow): + def __init__(self, app: Adw.Application) -> None: + super().__init__(application=app, title=APP_NAME) + self.set_default_size(760, 480) + self.set_icon_name(APP_ICON_NAME) + + about_action = Gio.SimpleAction.new("about", None) + about_action.connect("activate", lambda _a, _p: self.show_about_dialog()) + self.add_action(about_action) + + menu = Gio.Menu() + menu.append(f"About {APP_NAME}", "win.about") + + menu_button = Gtk.MenuButton(icon_name="open-menu-symbolic") + menu_button.set_menu_model(menu) + menu_button.set_tooltip_text("Main menu") + + refresh_button = Gtk.Button.new_from_icon_name("view-refresh-symbolic") + refresh_button.set_tooltip_text("Refresh") + refresh_button.connect("clicked", lambda _b: self.refresh()) + + add_button = Gtk.Button(label="Add Share") + add_button.set_tooltip_text("Add share") + add_button.add_css_class("suggested-action") + add_button.connect("clicked", lambda _b: self.show_add_dialog()) + + header = Adw.HeaderBar() + header.pack_start(add_button) + header.pack_end(menu_button) + header.pack_end(refresh_button) + + self.toast_overlay = Adw.ToastOverlay() + + # Content area; Tasks 6-8 replace the list/empty children inside it. + self.content_box = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=0) + self.toast_overlay.set_child(self.content_box) + + self.empty_label = Gtk.Label(label="No SMB mounts found.") + self.empty_label.add_css_class("dim-label") + self.empty_label.set_margin_top(32) + + self.list_box = Gtk.ListBox() + self.list_box.set_selection_mode(Gtk.SelectionMode.NONE) + self.list_box.add_css_class("boxed-list") + + scroller = Gtk.ScrolledWindow() + scroller.set_policy(Gtk.PolicyType.NEVER, Gtk.PolicyType.AUTOMATIC) + scroller.set_child(self.list_box) + scroller.set_vexpand(True) + scroller.set_margin_top(16) + scroller.set_margin_bottom(16) + scroller.set_margin_start(16) + scroller.set_margin_end(16) + + self.content_box.append(scroller) + self.content_box.append(self.empty_label) + + toolbar_view = Adw.ToolbarView() + toolbar_view.add_top_bar(header) + toolbar_view.set_content(self.toast_overlay) + self.set_content(toolbar_view) + + self.refresh() + + def show_toast(self, message: str) -> None: + self.toast_overlay.add_toast(Adw.Toast(title=message)) +``` + +Leave the remaining `MainWindow` methods (`refresh`, `row_for`, `show_add_dialog`, `show_about_dialog`, `mount_created`, `open_mount_folder`, `upgrade_mount`, `toggle_mount`, `confirm_delete`) unchanged. They still operate on `self.list_box` and `self.empty_label`. + +- [ ] **Step 2: Manual verification** + +Run: `python3 mount_manager.py` +Expected: +- Header bar shows "Add Share" (suggested-action, blue) on the left; refresh and menu buttons on the right. +- Window title reads "SMB Mount Manager". +- The mount list shows the same rows as before (we have not yet converted them). +- Add Share dialog still opens (uses the unmodified `AddShareWindow` for now). +- About menu still works (uses the unmodified `Gtk.AboutDialog`). +- Refreshing works. + +- [ ] **Step 3: Run unit tests** + +Run: `python3 -m unittest discover -s tests -v` +Expected: `OK`. + +- [ ] **Step 4: Commit** + +```bash +git add mount_manager_ui.py +git commit -m "feat(ui): adopt Adw.ApplicationWindow with ToolbarView and ToastOverlay" +``` + +--- + +## Task 6: `mount_status_line()` helper + +**Files:** +- Modify: `mount_manager_ui.py` (add helper at module scope) +- Create: `tests/test_mount_status_line.py` + +A pure helper that builds the subtitle string used by each `AdwActionRow`. Task 7 uses it. + +- [ ] **Step 1: Write the failing test** + +Create `tests/test_mount_status_line.py`: + +```python +"""Unit tests for the AdwActionRow subtitle builder.""" + +import unittest +from pathlib import Path + +from mount_manager import DisplayedMount + + +def _mount(**overrides: object) -> DisplayedMount: + defaults = dict( + source="//host/share", + mount_point=Path("/mnt/mount-manager/share"), + status="Mounted", + active=True, + openable=True, + needs_upgrade=False, + managed=True, + managed_record=None, + ) + defaults.update(overrides) + return DisplayedMount(**defaults) # type: ignore[arg-type] + + +class MountStatusLineTest(unittest.TestCase): + def test_combines_mount_point_and_status(self) -> None: + from mount_manager_ui import mount_status_line + + line = mount_status_line(_mount(status="Mounted")) + self.assertEqual(line, "/mnt/mount-manager/share · Mounted") + + def test_idle_status(self) -> None: + from mount_manager_ui import mount_status_line + + line = mount_status_line(_mount(status="Idle", active=False)) + self.assertEqual(line, "/mnt/mount-manager/share · Idle") + + def test_unmanaged_uses_unmanaged_status(self) -> None: + from mount_manager_ui import mount_status_line + + line = mount_status_line( + _mount( + mount_point=Path("/mnt/elsewhere"), + status="Mounted (not managed)", + managed=False, + ) + ) + self.assertEqual(line, "/mnt/elsewhere · Mounted (not managed)") + + +if __name__ == "__main__": + unittest.main() +``` + +- [ ] **Step 2: Run the test to confirm it fails** + +Run: `python3 -m unittest tests.test_mount_status_line -v` +Expected: `ImportError: cannot import name 'mount_status_line' from 'mount_manager_ui'`. + +- [ ] **Step 3: Add the helper at module scope in `mount_manager_ui.py`** + +After the `apply_style_manager` function (and **outside** `run_gui`), add: + +```python +def mount_status_line(mount: DisplayedMount) -> str: + """Build the AdwActionRow subtitle for a mount: `` · ``.""" + return f"{mount.mount_point} \u00b7 {mount.status}" +``` + +- [ ] **Step 4: Run the test to confirm it passes** + +Run: `python3 -m unittest tests.test_mount_status_line -v` +Expected: three tests pass, `OK`. + +- [ ] **Step 5: Commit** + +```bash +git add mount_manager_ui.py tests/test_mount_status_line.py +git commit -m "feat(ui): add mount_status_line helper" +``` + +--- + +## Task 7: Replace `row_for()` with `AdwPreferencesGroup` + `AdwActionRow` + +**Files:** +- Modify: `mount_manager_ui.py` (`MainWindow` class) + +Replace the `boxed-list` `Gtk.ListBox` set up in Task 5 with an `Adw.PreferencesPage` containing one `Adw.PreferencesGroup`. Replace `row_for()` to return an `Adw.ActionRow` with the controls in the order: **switch, open-folder (or upgrade), kebab**. Unmanaged rows show a "Not managed" label and no controls. + +- [ ] **Step 1: Replace the list scaffolding inside `MainWindow.__init__`** + +In the body of `MainWindow.__init__` (the part added in Task 5), replace the `self.list_box`, `scroller`, and the calls that append them to `self.content_box` with: + +```python + self.preferences_page = Adw.PreferencesPage() + self.preferences_page.set_vexpand(True) + + self.mount_group = Adw.PreferencesGroup() + self.mount_group.set_title("SMB Shares") + self.preferences_page.add(self.mount_group) + + self.content_box.append(self.preferences_page) + self.content_box.append(self.empty_label) +``` + +The variables `self.list_box` and `scroller` no longer exist. Update `MainWindow.refresh` (next step) accordingly. + +- [ ] **Step 2: Rewrite `MainWindow.refresh`** + +Replace the existing `refresh` method body with: + +```python + def refresh(self) -> None: + child = self.mount_group.get_first_child() + # Remove any previously added rows. Adw.PreferencesGroup exposes them + # via .remove(); iterating with get_first_child() is the safe pattern. + rows_to_remove = [] + row = child + while row is not None: + rows_to_remove.append(row) + row = row.get_next_sibling() + for row in rows_to_remove: + # Only ActionRow children we added belong here; leave internal + # widgets of the group untouched by filtering on the type we add. + if isinstance(row, Adw.ActionRow): + self.mount_group.remove(row) + + mounts = load_displayed_mounts() + self.empty_label.set_visible(not mounts) + self.preferences_page.set_visible(bool(mounts)) + + for mount in mounts: + self.mount_group.add(self.row_for(mount)) +``` + +> **Note:** `Adw.PreferencesGroup` keeps its title/description widgets internally; the `isinstance(row, Adw.ActionRow)` filter avoids accidentally removing them. If a future Adw release exposes `remove_all()`, that becomes a one-liner. + +- [ ] **Step 3: Rewrite `MainWindow.row_for`** + +Replace the existing `row_for` method with: + +```python + def row_for(self, mount: DisplayedMount) -> Adw.ActionRow: + row = Adw.ActionRow() + row.set_title(GLib_markup_escape(mount.source)) + row.set_subtitle(GLib_markup_escape(mount_status_line(mount))) + + if not mount.managed or mount.managed_record is None: + not_managed_label = Gtk.Label(label="Not managed") + not_managed_label.add_css_class("dim-label") + not_managed_label.set_valign(Gtk.Align.CENTER) + row.add_suffix(not_managed_label) + return row + + record = mount.managed_record + + mount_switch = Gtk.Switch() + mount_switch.set_valign(Gtk.Align.CENTER) + mount_switch.set_active(mount.active) + mount_switch.set_sensitive(not mount.needs_upgrade) + if mount.needs_upgrade: + mount_switch.set_tooltip_text("Upgrade this older mount before enabling it") + else: + mount_switch.set_tooltip_text( + "Enable or disable on-demand access for this managed mount" + ) + mount_switch.connect( + "notify::active", + lambda switch, _param: self.toggle_mount(record, switch), + ) + row.add_suffix(mount_switch) + + if mount.needs_upgrade: + upgrade_button = Gtk.Button(label="Upgrade") + upgrade_button.set_valign(Gtk.Align.CENTER) + upgrade_button.set_tooltip_text( + "Upgrade mount units using the existing encrypted credentials" + ) + upgrade_button.add_css_class("suggested-action") + upgrade_button.connect("clicked", lambda _b: self.upgrade_mount(record)) + row.add_suffix(upgrade_button) + else: + open_button = Gtk.Button.new_from_icon_name("folder-open-symbolic") + open_button.set_valign(Gtk.Align.CENTER) + open_button.add_css_class("flat") + open_button.set_sensitive(mount.openable) + open_button.set_tooltip_text( + "Open mount folder" + if mount.openable + else "Enable on-demand access to open its folder" + ) + open_button.connect("clicked", lambda _b: self.open_mount_folder(record)) + row.add_suffix(open_button) + + menu = Gio.Menu() + menu.append("Delete\u2026", f"row.delete::{record.manager_id}") + + row_action_group = Gio.SimpleActionGroup() + delete_action = Gio.SimpleAction.new("delete", GLib_VariantType("s")) + delete_action.connect( + "activate", lambda _a, _p, r=record: self.confirm_delete(r) + ) + row_action_group.add_action(delete_action) + row.insert_action_group("row", row_action_group) + + menu_button = Gtk.MenuButton() + menu_button.set_valign(Gtk.Align.CENTER) + menu_button.set_icon_name("view-more-symbolic") + menu_button.add_css_class("flat") + menu_button.set_menu_model(menu) + menu_button.set_tooltip_text("More actions") + row.add_suffix(menu_button) + + return row +``` + +- [ ] **Step 4: Add the small GLib helpers used above** + +At the **top** of `mount_manager_ui.py`, just under the existing `from gi.repository import …` line, add: + +```python +from gi.repository import GLib # noqa: E402 + + +def GLib_markup_escape(text: str) -> str: + """Escape Pango markup characters in row titles/subtitles.""" + return GLib.markup_escape_text(text, -1) + + +def GLib_VariantType(spec: str) -> GLib.VariantType: + return GLib.VariantType.new(spec) +``` + +(These exist as tiny wrappers so the code reads cleanly.) + +- [ ] **Step 5: Manual verification** + +Run: `python3 mount_manager.py` +Expected: +- The mount list is rendered as a single boxed group titled "SMB Shares" with one row per mount. +- Each managed row shows: source as title, "` · `" as subtitle, then on the right edge: switch, open-folder button (or "Upgrade" button if `needs_upgrade`), then a kebab (⋯) button. +- Toggling the switch enables/disables on-demand access (verify with `systemctl status ` for one of your mounts). +- Open folder still opens the mount target in the file manager. +- Kebab → Delete… still opens the existing `DeleteMountWindow` (replaced in Task 10). +- Unmanaged mounts (e.g. an SMB mount you created outside this app) show a "Not managed" label and no controls. +- Switching system color scheme still toggles light/dark instantly. + +- [ ] **Step 6: Run unit tests** + +Run: `python3 -m unittest discover -s tests -v` +Expected: `OK`. + +- [ ] **Step 7: Commit** + +```bash +git add mount_manager_ui.py +git commit -m "feat(ui): render mounts as AdwPreferencesGroup with AdwActionRow" +``` + +--- + +## Task 8: `Adw.StatusPage` empty state + +**Files:** +- Modify: `mount_manager_ui.py` (`MainWindow`) + +Replace the dim "No SMB mounts found." label with an `Adw.StatusPage` that includes an action button. + +- [ ] **Step 1: Replace `self.empty_label` setup** + +In `MainWindow.__init__`, remove the `self.empty_label = Gtk.Label(...)`, `add_css_class("dim-label")`, and `set_margin_top(32)` lines added earlier. Replace with: + +```python + self.empty_page = Adw.StatusPage() + self.empty_page.set_icon_name("folder-remote-symbolic") + self.empty_page.set_title("No SMB shares") + self.empty_page.set_description("Click Add Share to mount one.") + self.empty_page.set_vexpand(True) + + empty_action = Gtk.Button(label="Add Share") + empty_action.set_halign(Gtk.Align.CENTER) + empty_action.add_css_class("suggested-action") + empty_action.add_css_class("pill") + empty_action.connect("clicked", lambda _b: self.show_add_dialog()) + self.empty_page.set_child(empty_action) +``` + +Update the `content_box.append(self.empty_label)` line added in Task 7 to: + +```python + self.content_box.append(self.empty_page) +``` + +- [ ] **Step 2: Update `refresh()`** + +Replace `self.empty_label.set_visible(not mounts)` with: + +```python + self.empty_page.set_visible(not mounts) +``` + +- [ ] **Step 3: Manual verification** + +Run: `python3 mount_manager.py` +Expected: +- If you have any mounts, behavior is unchanged. +- If you remove all mounts (delete them through the app), the empty status page appears centered with the folder-remote icon, the heading "No SMB shares", and a pill suggested-action "Add Share" button. Clicking it opens the Add Share flow. + +- [ ] **Step 4: Run unit tests** + +Run: `python3 -m unittest discover -s tests -v` +Expected: `OK`. + +- [ ] **Step 5: Commit** + +```bash +git add mount_manager_ui.py +git commit -m "feat(ui): replace empty label with Adw.StatusPage" +``` + +--- + +## Task 9: `AddShareDialog(Adw.Dialog)` — single page, progressive reveal + +**Files:** +- Modify: `mount_manager_ui.py` (`run_gui` body and `MainWindow.show_add_dialog`) + +Replace the existing `AddShareWindow(Gtk.Window)` class with `AddShareDialog(Adw.Dialog)`. The dialog uses a single `Adw.PreferencesPage` whose Credentials group is insensitive until the host check succeeds. The "Check host" button is replaced by an automatic debounced check (300 ms after the user stops typing). On success the dialog closes and the main window shows a toast. On failure inside the create flow, an `Adw.Banner` is shown in the dialog and the dialog stays open. + +- [ ] **Step 1: Replace the `AddShareWindow` definition** + +Inside `run_gui`, **delete** the entire `class AddShareWindow(Gtk.Window):` block. In its place add: + +```python + class AddShareDialog(Adw.Dialog): + def __init__(self, main_window: "MainWindow") -> None: + super().__init__() + self.set_title("Add SMB Share") + self.set_content_width(420) + self.main_window = main_window + self.share_path: SharePath | None = None + self._debounce_id: int = 0 + + self.cancel_button = Gtk.Button(label="Cancel") + self.cancel_button.connect("clicked", lambda _b: self.close()) + + self.add_button = Gtk.Button(label="Add") + self.add_button.add_css_class("suggested-action") + self.add_button.set_sensitive(False) + self.add_button.connect("clicked", lambda _b: self._on_add_clicked()) + + header = Adw.HeaderBar() + header.set_show_start_title_buttons(False) + header.set_show_end_title_buttons(False) + header.pack_start(self.cancel_button) + header.pack_end(self.add_button) + + self.banner = Adw.Banner() + self.banner.set_revealed(False) + + page = Adw.PreferencesPage() + + share_group = Adw.PreferencesGroup() + share_group.set_title("Share") + page.add(share_group) + + self.path_row = Adw.EntryRow() + self.path_row.set_title("Share path") + self.path_row.set_tooltip_text( + "Example: //192.168.1.2/sharename or //hostname/sharename" + ) + self.path_row.connect("changed", lambda _r: self._on_path_changed()) + share_group.add(self.path_row) + + self.host_spinner = Gtk.Spinner() + self.host_spinner.set_valign(Gtk.Align.CENTER) + self.host_spinner.set_visible(False) + self.path_row.add_suffix(self.host_spinner) + + self.host_status_icon = Gtk.Image() + self.host_status_icon.set_valign(Gtk.Align.CENTER) + self.host_status_icon.set_visible(False) + self.path_row.add_suffix(self.host_status_icon) + + self.credentials_group = Adw.PreferencesGroup() + self.credentials_group.set_title("Credentials") + self.credentials_group.set_sensitive(False) + page.add(self.credentials_group) + + self.user_row = Adw.EntryRow() + self.user_row.set_title("Username") + self.user_row.connect("changed", lambda _r: self._update_add_sensitive()) + self.credentials_group.add(self.user_row) + + self.password_row = Adw.PasswordEntryRow() + self.password_row.set_title("Password") + self.password_row.connect("changed", lambda _r: self._update_add_sensitive()) + self.credentials_group.add(self.password_row) + + body = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=0) + body.append(self.banner) + body.append(page) + + toolbar = Adw.ToolbarView() + toolbar.add_top_bar(header) + toolbar.set_content(body) + self.set_child(toolbar) + + def _show_banner(self, message: str) -> None: + self.banner.set_title(message) + self.banner.set_revealed(True) + + def _hide_banner(self) -> None: + self.banner.set_revealed(False) + + def _set_host_status(self, *, ok: bool | None, message: str) -> None: + self.host_spinner.set_visible(False) + self.host_spinner.stop() + if ok is None: + self.host_status_icon.set_visible(False) + self.path_row.set_title("Share path") + return + if ok: + self.host_status_icon.set_from_icon_name("emblem-ok-symbolic") + else: + self.host_status_icon.set_from_icon_name("dialog-error-symbolic") + self.host_status_icon.set_visible(True) + self.host_status_icon.set_tooltip_text(message) + + def _on_path_changed(self) -> None: + self.share_path = None + self.credentials_group.set_sensitive(False) + self._update_add_sensitive() + self._hide_banner() + self._set_host_status(ok=None, message="") + if self._debounce_id: + GLib.source_remove(self._debounce_id) + self._debounce_id = 0 + text = self.path_row.get_text().strip() + if not text: + return + self._debounce_id = GLib.timeout_add(300, self._run_host_check) + + def _run_host_check(self) -> bool: + self._debounce_id = 0 + self.host_spinner.set_visible(True) + self.host_spinner.start() + try: + share_path = check_smb_host_reachable(self.path_row.get_text()) + except MountManagerError as exc: + self._set_host_status(ok=False, message=str(exc)) + return False + except Exception as exc: + self._set_host_status(ok=False, message=f"Unexpected error: {exc}") + return False + + self.share_path = share_path + self._set_host_status(ok=True, message="Host is reachable") + self.credentials_group.set_sensitive(True) + self._update_add_sensitive() + return False # don't repeat the timeout + + def _update_add_sensitive(self) -> None: + ready = ( + self.share_path is not None + and bool(self.user_row.get_text().strip()) + and bool(self.password_row.get_text()) + ) + self.add_button.set_sensitive(ready) + + def _on_add_clicked(self) -> None: + if self.share_path is None: + return + share = self.share_path.source + username = self.user_row.get_text() + password = self.password_row.get_text() + try: + validate_credentials(username, password) + request_helper_create(share, username, password) + except MountManagerError as exc: + self._show_banner(str(exc)) + return + except Exception as exc: + self._show_banner(f"Unexpected error: {exc}") + return + + self.close() + self.main_window.refresh() + self.main_window.show_toast(f"{share} will mount when accessed.") +``` + +- [ ] **Step 2: Replace `MainWindow.show_add_dialog` and remove `MainWindow.mount_created`** + +In `MainWindow`, replace: + +```python + def show_add_dialog(self) -> None: + AddShareWindow(self, self.mount_created).present() +``` + +with: + +```python + def show_add_dialog(self) -> None: + AddShareDialog(self).present(self) +``` + +Delete the entire `mount_created` method — its work is now done inline by `AddShareDialog._on_add_clicked`. + +- [ ] **Step 3: Manual verification** + +Run: `python3 mount_manager.py` +Expected: +- Clicking "Add Share" presents an adaptive Adw dialog (desktop-style centered dialog on a desktop). +- Typing in the share path triggers an automatic host check after ~300 ms: spinner appears at the end of the row, then a green check or red error icon. The error icon's tooltip explains the failure. +- The Credentials group stays insensitive until the check passes. +- Once credentials are filled, "Add" becomes active. +- On success the dialog closes and the main window shows a toast at the bottom: "//host/share will mount when accessed." +- On failure (e.g. wrong password) a banner appears at the top of the dialog with the error; dialog stays open; you can correct and retry. +- Cancel closes the dialog with no side effects. + +- [ ] **Step 4: Run unit tests** + +Run: `python3 -m unittest discover -s tests -v` +Expected: `OK`. + +- [ ] **Step 5: Commit** + +```bash +git add mount_manager_ui.py +git commit -m "feat(ui): replace AddShareWindow with AdwDialog and progressive reveal" +``` + +--- + +## Task 10: `Adw.AlertDialog` for delete confirmation + +**Files:** +- Modify: `mount_manager_ui.py` + +Replace `DeleteMountWindow(Gtk.Window)` with an `Adw.AlertDialog`-based factory. Errors close the alert and surface as a toast in the main window. + +- [ ] **Step 1: Delete the existing `DeleteMountWindow` class** + +Inside `run_gui`, delete the entire `class DeleteMountWindow(Gtk.Window):` block. + +- [ ] **Step 2: Replace `MainWindow.confirm_delete`** + +In `MainWindow`, replace the existing `confirm_delete` method with: + +```python + def confirm_delete(self, record: ManagedMount) -> None: + alert = Adw.AlertDialog( + heading="Delete this SMB mount?", + body=( + f"Removes {record.source} and its systemd units. " + "The encrypted credentials will also be deleted." + ), + ) + alert.add_response("cancel", "Cancel") + alert.add_response("delete", "Delete") + alert.set_response_appearance( + "delete", Adw.ResponseAppearance.DESTRUCTIVE + ) + alert.set_default_response("cancel") + alert.set_close_response("cancel") + alert.connect("response", self._on_delete_response, record) + alert.present(self) + + def _on_delete_response( + self, _alert: Adw.AlertDialog, response: str, record: ManagedMount + ) -> None: + if response != "delete": + return + try: + request_helper_delete(record) + except MountManagerError as exc: + self.show_toast(f"Delete failed: {exc}") + return + except Exception as exc: + self.show_toast(f"Delete failed: {exc}") + return + self.refresh() + self.show_toast(f"{record.source} removed.") +``` + +- [ ] **Step 3: Manual verification** + +Run: `python3 mount_manager.py` +Expected: +- Kebab → Delete… on a managed row opens an Adw alert dialog with two buttons: "Cancel" (default) and "Delete" (destructive red appearance). +- Pressing Esc dismisses (cancel response). +- Cancel does nothing. +- Delete removes the mount, the list refreshes, and a toast appears: "//host/share removed." +- Simulate a failure (e.g. temporarily revoke polkit auth or rename `/usr/bin/pkexec`): the alert closes and a toast shows "Delete failed: …". + +- [ ] **Step 4: Run unit tests** + +Run: `python3 -m unittest discover -s tests -v` +Expected: `OK`. + +- [ ] **Step 5: Commit** + +```bash +git add mount_manager_ui.py +git commit -m "feat(ui): replace DeleteMountWindow with Adw.AlertDialog" +``` + +--- + +## Task 11: Replace `MessageWindow` with toasts + remove the class + +**Files:** +- Modify: `mount_manager_ui.py` + +`MessageWindow` is no longer used by Add Share or Delete after Tasks 9 and 10. The remaining call sites are in `open_mount_folder`, `upgrade_mount`, and `toggle_mount`. Convert each to a toast. Delete the `MessageWindow` class. + +- [ ] **Step 1: Update `MainWindow.open_mount_folder`** + +Replace its body with: + +```python + def open_mount_folder(self, record: ManagedMount) -> None: + if not record.mount_point.exists(): + self.show_toast(f"Mount folder does not exist: {record.mount_point}") + return + try: + run_command(["xdg-open", str(record.mount_point)]) + except MountManagerError as exc: + self.show_toast(f"Could not open {record.mount_point}: {exc}") +``` + +- [ ] **Step 2: Update `MainWindow.upgrade_mount`** + +Replace its body with: + +```python + def upgrade_mount(self, record: ManagedMount) -> None: + try: + request_helper_upgrade(record) + except MountManagerError as exc: + self.show_toast(f"Upgrade failed: {exc}") + return + except Exception as exc: + self.show_toast(f"Upgrade failed: {exc}") + return + self.refresh() + self.show_toast(f"{record.source} upgraded; will mount when accessed.") +``` + +- [ ] **Step 3: Update `MainWindow.toggle_mount`** + +Replace its body with: + +```python + def toggle_mount(self, record: ManagedMount, switch: Gtk.Switch) -> None: + enabled = switch.get_active() + switch.set_sensitive(False) + try: + request_helper_set_enabled(record, enabled) + except MountManagerError as exc: + self.show_toast(f"Toggle failed: {exc}") + except Exception as exc: + self.show_toast(f"Toggle failed: {exc}") + finally: + self.refresh() +``` + +- [ ] **Step 4: Delete the `MessageWindow` class** + +Inside `run_gui`, delete the entire `class MessageWindow(Gtk.Window):` block. + +- [ ] **Step 5: Manual verification** + +Run: `python3 mount_manager.py` +Expected: +- Successful upgrade → toast "//host/share upgraded; will mount when accessed." +- Toggling a switch off then on works without modal interruption; failures surface as toasts. +- Open folder failure (try renaming the mount target) shows a toast, not a window. +- No remaining references to `MessageWindow` (verify with `grep MessageWindow mount_manager_ui.py` — should return nothing). + +- [ ] **Step 6: Run unit tests** + +Run: `python3 -m unittest discover -s tests -v` +Expected: `OK`. + +- [ ] **Step 7: Commit** + +```bash +git add mount_manager_ui.py +git commit -m "feat(ui): replace MessageWindow with AdwToast notifications" +``` + +--- + +## Task 12: `Adw.AboutDialog` + +**Files:** +- Modify: `mount_manager_ui.py` (`MainWindow.show_about_dialog`) + +- [ ] **Step 1: Replace `show_about_dialog`** + +Replace the existing `show_about_dialog` method on `MainWindow` with: + +```python + def show_about_dialog(self) -> None: + about = Adw.AboutDialog( + application_name=APP_NAME, + application_icon=APP_ICON_NAME, + developer_name=APP_DEVELOPERS[0] if APP_DEVELOPERS else "", + website=APP_WEBSITE, + issue_url=f"{APP_WEBSITE}/issues", + license_type=Gtk.License.GPL_3_0_ONLY, + comments="Create and manage on-demand SMB mounts.", + ) + about.set_developers(APP_DEVELOPERS) + about.present(self) +``` + +- [ ] **Step 2: Manual verification** + +Run: `python3 mount_manager.py` +Expected: +- Menu → "About SMB Mount Manager" presents the modern Adw about dialog with the app icon, name, version-less header (Adw shows the application_name), developer credit, website link, and license tab. +- No deprecation warning in stderr about `Gtk.AboutDialog`. + +- [ ] **Step 3: Run unit tests** + +Run: `python3 -m unittest discover -s tests -v` +Expected: `OK`. + +- [ ] **Step 4: Commit** + +```bash +git add mount_manager_ui.py +git commit -m "feat(ui): use Adw.AboutDialog" +``` + +--- + +## Task 13: Packaging and README updates + +**Files:** +- Modify: `packaging/build-appimage.sh` +- Modify: `README.md` + +- [ ] **Step 1: Update `packaging/build-appimage.sh`** + +The AppImage installs `mount_manager.py` to `$appdir/usr/bin/mount-manager` (the executable script). When Python runs that script, `sys.path[0]` is `/usr/bin` (the script's directory), so placing `mount_manager_ui.py` in the same directory makes `import mount_manager_ui` resolve correctly without a shim. + +In `packaging/build-appimage.sh`, immediately after the line: + +```bash +install -D -m 0755 "$repo_root/mount_manager.py" "$appdir/usr/bin/mount-manager" +``` + +(currently line 90), add: + +```bash +install -D -m 0644 "$repo_root/mount_manager_ui.py" "$appdir/usr/bin/mount_manager_ui.py" +``` + +No other build-script changes are needed. The patch in `packaging/appimage-helper.patch` only touches `mount-manager` (the renamed `mount_manager.py`) and is unaffected by the new file, because the privileged helper subprocess does not import the UI module. + +- [ ] **Step 2: Update `README.md` requirements section** + +In `README.md`, find the "Requirements" section. After the line about systemd 258, add: + +```markdown +libadwaita 1.5 or newer. The app refuses to start on older versions. +``` + +- [ ] **Step 3: Update `README.md` install commands** + +In the "Test as an installed app on Bazzite" section, find the block of `sudo install -D …` commands. Immediately after the existing line for `mount_manager.py`, add: + +```bash +sudo install -D -m 0644 mount_manager_ui.py /usr/bin/mount_manager_ui.py +``` + +This places the UI module next to the executable so `python3 /usr/bin/mount-manager` can import it (Python adds the script's directory to `sys.path` automatically). + +- [ ] **Step 4: Manual verification** + +Run the README's documented install commands on a Bazzite test host (or VM). Verify `mount-manager` launches with the new Adw UI from the installed path. Confirm `which mount-manager` still resolves and `mount-manager --helper create < input` still works as a privileged subprocess (the helper code path is unchanged but the import path must resolve when re-execed under pkexec). + +- [ ] **Step 5: Commit** + +```bash +git add packaging/build-appimage.sh README.md +git commit -m "build: include mount_manager_ui in packaging and document libadwaita requirement" +``` + +--- + +## Final verification + +- [ ] **Run the full test suite** + +Run: `python3 -m unittest discover -s tests -v` +Expected: all tests pass. + +- [ ] **End-to-end smoke on Bazzite** + +Run `python3 mount_manager.py` from a desktop session and exercise every flow: +1. Empty state appears when there are no mounts; clicking "Add Share" from the empty state opens the dialog. +2. Add a real share end-to-end → toast on success → row appears. +3. Toggle the switch → systemctl reports the automount unit enabled/disabled accordingly. +4. Open folder works. +5. Delete confirmation works and surfaces toast on success. +6. Failure paths surface toasts/banners as documented. +7. Color scheme follows system preference. +8. About dialog shows Adw layout. + +- [ ] **Grep for orphaned references** + +Run: `grep -nE 'MessageWindow|AddShareWindow|DeleteMountWindow|APP_CSS|apply_theme' mount_manager.py mount_manager_ui.py` +Expected: no matches in either file. + +Run: `grep -nE 'Gtk\.AboutDialog' mount_manager.py mount_manager_ui.py` +Expected: no matches. diff --git a/docs/superpowers/specs/2026-05-28-libadwaita-migration-design.md b/docs/superpowers/specs/2026-05-28-libadwaita-migration-design.md new file mode 100644 index 0000000..2fc61ff --- /dev/null +++ b/docs/superpowers/specs/2026-05-28-libadwaita-migration-design.md @@ -0,0 +1,215 @@ +# libadwaita UI migration — design + +**Status:** approved (draft, pre-implementation) +**Date:** 2026-05-28 + +## Goal + +Migrate the Mount Manager GUI from plain GTK 4 widgets to libadwaita so the app +matches the look and behavior of native GNOME / Bazzite applications, and +remove the custom CSS and dark-mode detection currently used to approximate +that look. + +The privileged helper-mode subprocess, polkit invocation, systemd-creds +handling, mount-unit generation, and credential storage paths are out of scope +and must not change. + +## Approach + +In-place migration of the existing code, with a single targeted refactor: the +GUI is moved out of `mount_manager.py` into a new sibling module so that +`mount_manager.py` retains only the data models, systemd / credential plumbing, +and helper-mode subprocess entry point. + +The migration targets **libadwaita ≥ 1.5** so that `Adw.Dialog` and +`Adw.AlertDialog` are available. The app gains an explicit version check at +startup, parallel to today's systemd 258 check, that refuses to start with a +clear error if the host's libadwaita is too old. + +## File layout + +- `mount_manager.py` + - Keeps everything it has today **except** the body of `run_gui()` and the + UI classes nested inside it. + - `run_gui()` becomes a thin shim: + `from mount_manager_ui import run_gui as _run_gui; return _run_gui()`. + - Helper mode (`run_helper_mode`, `--helper` arg), data models + (`ManagedMount`, `DisplayedMount`, `SharePath`), systemd / credential + helpers, polkit handoff (`request_helper_*`), and `main()` stay put. + - `import_gtk()`, `apply_theme()`, and the `APP_CSS` constant are removed. +- `mount_manager_ui.py` *(new)* + - Module-level `gi.require_version("Gtk", "4.0")` and + `gi.require_version("Adw", "1")`, followed by `from gi.repository import …`. + - Defines: `ensure_libadwaita_supported()`, `apply_style_manager()`, + `MainWindow`, `AddShareDialog`, `DeleteAlertDialog` (thin wrapper around + `Adw.AlertDialog`), `MountManagerApplication`, and a `run_gui()` entry + point. + - Imports data models, constants, and helper-invocation functions from + `mount_manager`. +- `packaging/build-appimage.sh` — install the new file alongside + `mount_manager.py` (one additional copy/install line). +- `README.md` — add `mount_manager_ui.py` to the "Test as an installed app on + Bazzite" install commands, and add `libadwaita ≥ 1.5` to the requirements + section. + +## Window & theming + +- `MountManagerApplication` becomes `Adw.Application`. Application ID and + flags unchanged. +- `MainWindow` becomes `Adw.ApplicationWindow` containing an + `Adw.ToolbarView`. The top bar is an `Adw.HeaderBar`; the content area is an + `Adw.ToastOverlay` wrapping the list / status-page widget. +- The window title is `APP_NAME`; the icon name is unchanged. No manual title + widget is set — libadwaita derives the header title from the window title. +- Theming: `APP_CSS` and `apply_theme()` are deleted. + `Adw.StyleManager.get_default().set_color_scheme(Adw.ColorScheme.DEFAULT)` is + called once at startup so the app follows the system / portal preference + automatically. + +### Header bar + +- Start side: a suggested-action **Add Share** button (text label, no icon). +- End side: a refresh icon button (`view-refresh-symbolic`), then a menu + button (`open-menu-symbolic`) whose menu contains a single `About` entry. + +## Mount list + +- The content is an `Adw.Clamp` wrapping an `Adw.PreferencesPage` with one + `Adw.PreferencesGroup` titled "SMB Shares". +- Each mount is rendered as an `Adw.ActionRow`: + - Title: the share source (e.g. `//192.168.1.10/media`). + - Subtitle: the mount point and a short status string + (`/mnt/mount-manager/media · Mounted`, `… · Idle`, `… · Needs upgrade`, + `… · Mounted (not managed)`). + - Trailing widgets, in order: + 1. **Switch** — enables / disables the systemd automount, same semantics as + today's `mount_switch`. Insensitive when the row is unmanaged or needs + upgrading. + 2. **Open folder** icon button (`folder-open-symbolic`) — sensitive only + when on-demand access is active, matching today's `open_button.set_sensitive` + logic. + 3. **Primary action** (only when applicable): for rows that need an + upgrade, an inline button labeled "Upgrade" is shown in place of the + open-folder button (matches today's behavior of swapping these two). + 4. **Kebab** (`Gtk.MenuButton` with `view-more-symbolic`) — menu contains a + destructive "Delete…" entry. +- Unmanaged mounts: no switch, no open button, no kebab. The trailing area + shows a dim "Not managed" label as today. +- Tooltips on the switch and open button preserve today's exact strings. + +## Empty state + +When `load_displayed_mounts()` returns no rows, the preferences page is +hidden and replaced by an `Adw.StatusPage`: + +- icon: `folder-remote-symbolic` +- title: "No SMB shares" +- description: "Click *Add Share* to mount one." +- child: a suggested-action button "Add Share" that opens the Add Share dialog + (same handler as the header button). + +## Add Share dialog + +`AddShareDialog(Adw.Dialog)` — single page, progressive reveal. + +- Header: `Adw.HeaderBar` with `Cancel` (start) and a suggested-action `Add` + (end). `Add` is insensitive until the host check has succeeded and both + credential fields are non-empty. +- Body: `Adw.Clamp` → `Adw.PreferencesPage` with two + `Adw.PreferencesGroup`s: + - **Share** group: + - `Adw.EntryRow` titled "Share path". Placeholder example: + `//192.168.1.2/sharename or //hostname/sharename`. + - The host check (currently a separate "Check host" button) runs + automatically after a short typing debounce once the entered path + parses. A spinner is shown in the row's apply / trailing area while the + check is in flight, replaced by a green check icon on success or a red + error icon on failure. The row's subtitle conveys the result text. + - **Credentials** group: + - `Adw.EntryRow` titled "Username". + - `Adw.PasswordEntryRow` titled "Password". + - The group's `sensitive` property is bound to "host check succeeded". +- Submitting `Add` runs the existing test-mount → helper-create flow on a + worker thread (today's logic is preserved). On success the dialog closes, + the main window's list refreshes, and a toast is shown. On failure an + `Adw.Banner` is added at the top of the dialog body with the error message; + the dialog stays open so the user can correct input and retry. + +## Delete confirmation + +`DeleteAlertDialog` is an `Adw.AlertDialog`: + +- Heading: "Delete this SMB mount?" +- Body: "Removes `{record.source}` and its systemd units. The encrypted + credentials will also be deleted." +- Responses: `cancel` ("Cancel", default) and `delete` ("Delete", + destructive appearance). + +On confirm, the existing helper-delete flow runs. On failure, the alert +closes and a toast is shown with the error; if the error message is long, the +toast has a "Details" button that opens a transient `Adw.AlertDialog` with the +full text. + +## About dialog + +`Adw.AboutDialog` populated from the existing constants: + +- application name: `APP_NAME` +- application icon: `APP_ICON_NAME` +- developer name(s): `APP_DEVELOPERS` +- website: `APP_WEBSITE` +- license type: `Gtk.License.GPL_3_0_ONLY` +- comments: "Create and manage on-demand SMB mounts." + +The current `Gtk.AboutDialog` invocation is removed. + +## Toasts and banners (replacing MessageWindow) + +`MessageWindow` is deleted. Every existing call site is reclassified: + +| Existing call | New behavior | +| --- | --- | +| `MessageWindow(self, "SMB Mount Created", …)` | `Adw.Toast` in main window. | +| `MessageWindow(self, "SMB Mount Upgraded", …)` | `Adw.Toast` in main window. | +| `MessageWindow(self, "Open Folder Failed", …)` | `Adw.Toast` (with "Details" button if message is long). | +| `MessageWindow(self, "Upgrade Failed", …)` | `Adw.Toast` (with "Details" button). | +| `MessageWindow(self, "Mount Toggle Failed", …)` | `Adw.Toast` (with "Details" button). | +| Test-mount failure inside Add Share | `Adw.Banner` at top of Add Share dialog, dialog stays open. | +| Delete failure inside Delete confirmation | Alert closes, error shown as toast in main window. | + +## Startup checks + +A new `ensure_libadwaita_supported()` function runs before window creation. It +checks the linked libadwaita version (via `Adw.MAJOR_VERSION`, +`Adw.MINOR_VERSION`) and refuses to start with a clear stderr message if the +version is below 1.5. This mirrors the existing `require_systemd_support()` +pattern. + +## Out of scope + +- Helper-mode subprocess (`--helper create|delete|upgrade|set-enabled`). +- polkit / `pkexec` invocation. +- systemd-creds encryption and credential file paths. +- Mount-unit generation and the `/mnt/mount-manager` / `/etc/mount-manager` + layout. +- `argparse`, `main()`, and the `--helper` entry point in `mount_manager.py`. +- No new third-party Python dependencies. The only new runtime dependency is + the system libadwaita ≥ 1.5 typing, already present on supported targets. +- RPM spec changes are not in this repo; only README and AppImage notes are + updated here. + +## Risks + +- **Host libadwaita version drift.** The AppImage runs against the host's + libadwaita. Systems with libadwaita < 1.5 will be rejected at startup with a + clear message. Bazzite and current Fedora ship ≥ 1.5, so impact is limited + to outliers. +- **Toast vs. window for success messages.** The user no longer dismisses a + modal window after each successful operation. This is a deliberate UX + improvement but should be verified by manual testing on a real Bazzite + install before release. +- **Automatic host check on type.** Removing the explicit "Check host" button + means hostname / DNS lookups run as the user types (debounced). Network + errors and slow DNS need to be surfaced clearly in the row's status area to + avoid the dialog feeling broken. The existing host-check function is reused + unchanged; only its invocation timing changes. From dd15f3c49dace78a63212385712da404cc905793 Mon Sep 17 00:00:00 2001 From: meowtypes Date: Thu, 28 May 2026 03:01:00 -0700 Subject: [PATCH 02/41] test: add unittest scaffolding with import smoke test --- tests/__init__.py | 0 tests/test_smoke.py | 14 ++++++++++++++ 2 files changed, 14 insertions(+) create mode 100644 tests/__init__.py create mode 100644 tests/test_smoke.py diff --git a/tests/__init__.py b/tests/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/tests/test_smoke.py b/tests/test_smoke.py new file mode 100644 index 0000000..030792f --- /dev/null +++ b/tests/test_smoke.py @@ -0,0 +1,14 @@ +"""Smoke test ensuring the test harness can import the main module.""" + +import unittest + + +class ImportSmokeTest(unittest.TestCase): + def test_import_mount_manager(self) -> None: + import mount_manager # noqa: F401 + + self.assertTrue(hasattr(mount_manager, "main")) + + +if __name__ == "__main__": + unittest.main() From 9c207e11f1a50faaf1ba7a0cbc186c2d14ac5dbc Mon Sep 17 00:00:00 2001 From: meowtypes Date: Thu, 28 May 2026 03:04:20 -0700 Subject: [PATCH 03/41] feat: add libadwaita version comparator --- mount_manager.py | 9 +++++++++ tests/test_libadwaita_support.py | 26 ++++++++++++++++++++++++++ 2 files changed, 35 insertions(+) create mode 100644 tests/test_libadwaita_support.py diff --git a/mount_manager.py b/mount_manager.py index 712b968..c6efe02 100644 --- a/mount_manager.py +++ b/mount_manager.py @@ -50,6 +50,15 @@ # Mount-unit credentials (LoadCredentialEncrypted=) require this systemd version. MIN_SYSTEMD_VERSION = 258 +# Adw.Dialog and Adw.AlertDialog require libadwaita 1.5 or newer. +MIN_LIBADWAITA_VERSION: tuple[int, int] = (1, 5) + + +def _libadwaita_supports(major: int, minor: int) -> bool: + """Return True if the given libadwaita (major, minor) meets the app's minimum.""" + return (major, minor) >= MIN_LIBADWAITA_VERSION + + APP_CSS = """ window { background: @theme_bg_color; diff --git a/tests/test_libadwaita_support.py b/tests/test_libadwaita_support.py new file mode 100644 index 0000000..db2cc40 --- /dev/null +++ b/tests/test_libadwaita_support.py @@ -0,0 +1,26 @@ +"""Unit tests for the libadwaita version comparator.""" + +import unittest + +from mount_manager import _libadwaita_supports + + +class LibadwaitaSupportsTest(unittest.TestCase): + def test_minimum_supported_version(self) -> None: + self.assertTrue(_libadwaita_supports(1, 5)) + + def test_newer_minor_supported(self) -> None: + self.assertTrue(_libadwaita_supports(1, 7)) + + def test_newer_major_supported(self) -> None: + self.assertTrue(_libadwaita_supports(2, 0)) + + def test_older_minor_unsupported(self) -> None: + self.assertFalse(_libadwaita_supports(1, 4)) + + def test_older_major_unsupported(self) -> None: + self.assertFalse(_libadwaita_supports(0, 99)) + + +if __name__ == "__main__": + unittest.main() From b7aa443e608204cbd9c571c3dff062f44a6855ec Mon Sep 17 00:00:00 2001 From: meowtypes Date: Thu, 28 May 2026 03:11:01 -0700 Subject: [PATCH 04/41] refactor: split GUI code into mount_manager_ui module --- mount_manager.py | 605 +---------------------------------------- mount_manager_ui.py | 636 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 638 insertions(+), 603 deletions(-) create mode 100644 mount_manager_ui.py diff --git a/mount_manager.py b/mount_manager.py index c6efe02..04d362d 100644 --- a/mount_manager.py +++ b/mount_manager.py @@ -59,77 +59,6 @@ def _libadwaita_supports(major: int, minor: int) -> bool: return (major, minor) >= MIN_LIBADWAITA_VERSION -APP_CSS = """ -window { - background: @theme_bg_color; - color: @theme_fg_color; -} - -headerbar { - background: @theme_base_color; - color: @theme_text_color; -} - -.mount-root { - background: @theme_bg_color; -} - -.boxed-list { - background: @theme_base_color; - color: @theme_text_color; - border: 1px solid alpha(@theme_fg_color, 0.16); - border-radius: 8px; -} - -.boxed-list row { - background: transparent; - color: @theme_text_color; -} - -.boxed-list row:not(:last-child) { - border-bottom: 1px solid alpha(@theme_fg_color, 0.10); -} - -.dim-label { - opacity: 0.72; -} - -.error { - color: #c01c28; -} - -.success { - color: #26a269; -} - -button.headerbar-control, -menubutton.headerbar-control > button { - min-height: 34px; - min-width: 34px; - padding-top: 4px; - padding-bottom: 4px; -} - -button.add-share-button { - font-weight: 700; - padding-left: 12px; - padding-right: 12px; -} - -button.upgrade-action { - background: #26a269; - color: white; -} - -button.upgrade-action:hover { - background: #2ec27e; -} - -button.upgrade-action:active { - background: #1a7f52; -} -""" - HOST_RE = re.compile( r"^(?=.{1,253}$)(?:[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?\.)*" r"[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?$" @@ -1154,542 +1083,12 @@ def run_helper_mode(action: str) -> int: return 0 -def import_gtk() -> tuple[Any, Any, Any, Any]: - import gi - - gi.require_version("Gdk", "4.0") - gi.require_version("Gtk", "4.0") - gi.require_version("Pango", "1.0") - from gi.repository import Gdk, Gio, Gtk, Pango - - return Gdk, Gio, Gtk, Pango - - -def apply_theme(Gtk: Any, Gdk: Any) -> None: - settings = Gtk.Settings.get_default() - if settings is not None: - settings.set_property( - "gtk-application-prefer-dark-theme", - detect_color_scheme() == "dark", - ) - - display = Gdk.Display.get_default() - if display is None: - return - - Gtk.Window.set_default_icon_name(APP_ICON_NAME) - - provider = Gtk.CssProvider() - provider.load_from_data(APP_CSS.encode("utf-8")) - Gtk.StyleContext.add_provider_for_display( - display, - provider, - Gtk.STYLE_PROVIDER_PRIORITY_APPLICATION, - ) def run_gui() -> int: - Gdk, Gio, Gtk, Pango = import_gtk() - if not Gtk.init_check(): - print( - "GTK could not connect to your graphical session. Run this from your " - "desktop session, not a plain TTY.", - file=sys.stderr, - ) - return 1 - if Gdk.Display.get_default() is None: - print( - "GTK did not provide a usable display. Run this from your desktop " - "session, not a plain TTY.", - file=sys.stderr, - ) - return 1 - apply_theme(Gtk, Gdk) - - class AddShareWindow(Gtk.Window): - def __init__(self, parent: Gtk.Window, on_complete: Any) -> None: - super().__init__(title="Add SMB Share") - self.set_transient_for(parent) - self.set_modal(True) - self.set_default_size(560, -1) - self.set_resizable(False) - self.on_complete = on_complete - self.share_path: SharePath | None = None - - root = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=14) - root.set_margin_top(18) - root.set_margin_bottom(18) - root.set_margin_start(18) - root.set_margin_end(18) - self.set_child(root) - - self.path_box = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=8) - root.append(self.path_box) - - path_label = Gtk.Label(label="Please add share path") - path_label.set_xalign(0) - self.path_box.append(path_label) - - self.path_entry = Gtk.Entry() - self.path_entry.set_placeholder_text("//hostname/share") - self.path_entry.set_hexpand(True) - self.path_entry.connect("activate", lambda _entry: self.on_next_clicked()) - self.path_box.append(self.path_entry) - - path_help = Gtk.Label(label="Example: //192.168.1.2/sharename or //hostname/sharename") - path_help.set_xalign(0) - path_help.add_css_class("dim-label") - self.path_box.append(path_help) - - self.credentials_box = Gtk.Grid(column_spacing=12, row_spacing=10) - self.credentials_box.set_visible(False) - root.append(self.credentials_box) - - host_status_label = Gtk.Label(label="") - host_status_label.set_xalign(0) - host_status_label.add_css_class("success") - self.credentials_box.attach(host_status_label, 0, 0, 2, 1) - self.host_status_label = host_status_label - - user_label = Gtk.Label(label="Username") - user_label.set_xalign(0) - self.credentials_box.attach(user_label, 0, 1, 1, 1) - - self.user_entry = Gtk.Entry() - self.user_entry.set_hexpand(True) - self.user_entry.connect("activate", lambda _entry: self.password_entry.grab_focus()) - self.credentials_box.attach(self.user_entry, 1, 1, 1, 1) - - password_label = Gtk.Label(label="Password") - password_label.set_xalign(0) - self.credentials_box.attach(password_label, 0, 2, 1, 1) - - self.password_entry = Gtk.PasswordEntry() - self.password_entry.set_hexpand(True) - self.password_entry.connect("activate", lambda _entry: self.on_next_clicked()) - self.credentials_box.attach(self.password_entry, 1, 2, 1, 1) - - self.status_label = Gtk.Label() - self.status_label.set_xalign(0) - self.status_label.set_wrap(True) - self.status_label.add_css_class("dim-label") - self.status_label.set_visible(False) - root.append(self.status_label) - - buttons = Gtk.Box(orientation=Gtk.Orientation.HORIZONTAL, spacing=8) - buttons.set_halign(Gtk.Align.END) - root.append(buttons) - - cancel_button = Gtk.Button(label="Cancel") - cancel_button.connect("clicked", lambda _button: self.close()) - buttons.append(cancel_button) - - self.back_button = Gtk.Button(label="Back") - self.back_button.set_visible(False) - self.back_button.connect("clicked", lambda _button: self.show_path_step()) - buttons.append(self.back_button) - - self.next_button = Gtk.Button(label="Check host") - self.next_button.add_css_class("suggested-action") - self.next_button.connect("clicked", lambda _button: self.on_next_clicked()) - buttons.append(self.next_button) - - self.path_entry.grab_focus() - - def set_status(self, message: str, css_class: str) -> None: - self.status_label.remove_css_class("error") - self.status_label.remove_css_class("success") - self.status_label.add_css_class(css_class) - self.status_label.set_text(message) - self.status_label.set_visible(True) - - def show_path_step(self) -> None: - self.share_path = None - self.path_entry.set_sensitive(True) - self.path_box.set_visible(True) - self.credentials_box.set_visible(False) - self.back_button.set_visible(False) - self.next_button.set_label("Check host") - self.status_label.set_visible(False) - self.path_entry.grab_focus() - - def show_credentials_step(self, share_path: SharePath) -> None: - self.share_path = share_path - self.path_entry.set_sensitive(False) - self.path_box.set_visible(True) - self.credentials_box.set_visible(True) - self.host_status_label.set_text("Host is reachable. Please enter credentials.") - self.back_button.set_visible(True) - self.next_button.set_label("Create") - self.status_label.set_visible(False) - self.user_entry.grab_focus() - - def on_next_clicked(self) -> None: - if self.share_path is None: - self.check_host() - else: - self.create_share() - - def check_host(self) -> None: - try: - share_path = check_smb_host_reachable(self.path_entry.get_text()) - except MountManagerError as exc: - self.set_status(str(exc), "error") - return - except Exception as exc: - self.set_status(f"Unexpected error: {exc}", "error") - return - - self.show_credentials_step(share_path) - - def create_share(self) -> None: - if self.share_path is None: - self.set_status("Check the share path before entering credentials.", "error") - return - - share = self.share_path.source - username = self.user_entry.get_text() - password = self.password_entry.get_text() - - try: - validate_credentials(username, password) - self.set_status("Creating encrypted on-demand mount...", "success") - request_helper_create(share, username, password) - except MountManagerError as exc: - self.set_status(str(exc), "error") - return - except Exception as exc: - self.set_status(f"Unexpected error: {exc}", "error") - return - - self.close() - self.on_complete(share) - - class MessageWindow(Gtk.Window): - def __init__(self, parent: Gtk.Window, title: str, message: str) -> None: - super().__init__(title=title) - self.set_transient_for(parent) - self.set_modal(True) - self.set_default_size(420, -1) - self.set_resizable(False) - - root = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=14) - root.set_margin_top(18) - root.set_margin_bottom(18) - root.set_margin_start(18) - root.set_margin_end(18) - self.set_child(root) - - heading = Gtk.Label(label=title) - heading.add_css_class("title-3") - heading.set_xalign(0) - root.append(heading) - - label = Gtk.Label(label=message) - label.set_wrap(True) - label.set_xalign(0) - root.append(label) - - buttons = Gtk.Box(orientation=Gtk.Orientation.HORIZONTAL, spacing=8) - buttons.set_halign(Gtk.Align.END) - root.append(buttons) - - ok_button = Gtk.Button(label="OK") - ok_button.add_css_class("suggested-action") - ok_button.connect("clicked", lambda _button: self.close()) - buttons.append(ok_button) - - class DeleteMountWindow(Gtk.Window): - def __init__(self, parent: Gtk.Window, record: ManagedMount, on_complete: Any) -> None: - super().__init__(title="Delete SMB Mount") - self.set_transient_for(parent) - self.set_modal(True) - self.set_default_size(460, -1) - self.set_resizable(False) - self.record = record - self.on_complete = on_complete - - root = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=14) - root.set_margin_top(18) - root.set_margin_bottom(18) - root.set_margin_start(18) - root.set_margin_end(18) - self.set_child(root) - - heading = Gtk.Label(label="Delete SMB Mount") - heading.add_css_class("title-3") - heading.set_xalign(0) - root.append(heading) - - label = Gtk.Label(label=f"Delete {record.source} and remove its systemd units?") - label.set_wrap(True) - label.set_xalign(0) - root.append(label) - - self.error_label = Gtk.Label() - self.error_label.set_xalign(0) - self.error_label.set_wrap(True) - self.error_label.add_css_class("error") - self.error_label.set_visible(False) - root.append(self.error_label) - - buttons = Gtk.Box(orientation=Gtk.Orientation.HORIZONTAL, spacing=8) - buttons.set_halign(Gtk.Align.END) - root.append(buttons) - - cancel_button = Gtk.Button(label="Cancel") - cancel_button.connect("clicked", lambda _button: self.close()) - buttons.append(cancel_button) - - delete_button = Gtk.Button(label="Delete") - delete_button.add_css_class("destructive-action") - delete_button.connect("clicked", lambda _button: self.delete_share()) - buttons.append(delete_button) - - def show_error(self, message: str) -> None: - self.error_label.set_text(message) - self.error_label.set_visible(True) - - def delete_share(self) -> None: - try: - request_helper_delete(self.record) - except MountManagerError as exc: - self.show_error(str(exc)) - return - except Exception as exc: - self.show_error(f"Unexpected error: {exc}") - return - - self.close() - self.on_complete() - - class MainWindow(Gtk.ApplicationWindow): - def __init__(self, app: Gtk.Application) -> None: - super().__init__(application=app, title=APP_NAME) - self.set_default_size(760, 480) - self.set_icon_name(APP_ICON_NAME) - - header = Gtk.HeaderBar() - title = Gtk.Label(label=APP_NAME) - title.add_css_class("heading") - header.set_title_widget(title) - - refresh_button = Gtk.Button.new_from_icon_name("view-refresh-symbolic") - refresh_button.set_tooltip_text("Refresh") - refresh_button.add_css_class("headerbar-control") - refresh_button.connect("clicked", lambda _button: self.refresh()) - - about_action = Gio.SimpleAction.new("about", None) - about_action.connect("activate", lambda _action, _param: self.show_about_dialog()) - self.add_action(about_action) - - menu = Gio.Menu() - menu.append(f"About {APP_NAME}", "win.about") - - menu_button = Gtk.MenuButton() - menu_button.set_icon_name("open-menu-symbolic") - menu_button.set_menu_model(menu) - menu_button.set_tooltip_text("Main menu") - menu_button.add_css_class("headerbar-control") - - add_button = Gtk.Button(label="ADD SHARE") - add_button.set_tooltip_text("Add share") - add_button.add_css_class("suggested-action") - add_button.add_css_class("headerbar-control") - add_button.add_css_class("add-share-button") - add_button.connect("clicked", lambda _button: self.show_add_dialog()) - header.pack_start(add_button) - header.pack_end(menu_button) - header.pack_end(refresh_button) - - self.set_titlebar(header) - - root = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=12) - root.add_css_class("mount-root") - root.set_margin_top(16) - root.set_margin_bottom(16) - root.set_margin_start(16) - root.set_margin_end(16) - self.set_child(root) - - self.empty_label = Gtk.Label(label="No SMB mounts found.") - self.empty_label.add_css_class("dim-label") - self.empty_label.set_margin_top(32) - - self.list_box = Gtk.ListBox() - self.list_box.set_selection_mode(Gtk.SelectionMode.NONE) - self.list_box.add_css_class("boxed-list") - - scroller = Gtk.ScrolledWindow() - scroller.set_policy(Gtk.PolicyType.NEVER, Gtk.PolicyType.AUTOMATIC) - scroller.set_child(self.list_box) - scroller.set_vexpand(True) - root.append(scroller) - root.append(self.empty_label) - - self.refresh() - - def refresh(self) -> None: - while True: - row = self.list_box.get_first_child() - if row is None: - break - self.list_box.remove(row) - - mounts = load_displayed_mounts() - self.empty_label.set_visible(not mounts) - self.list_box.set_visible(bool(mounts)) - - for mount in mounts: - self.list_box.append(self.row_for(mount)) - - def row_for(self, mount: DisplayedMount) -> Gtk.ListBoxRow: - row = Gtk.ListBoxRow() - box = Gtk.Box(orientation=Gtk.Orientation.HORIZONTAL, spacing=12) - box.set_margin_top(10) - box.set_margin_bottom(10) - box.set_margin_start(12) - box.set_margin_end(12) - - mount_switch = Gtk.Switch() - mount_switch.set_valign(Gtk.Align.CENTER) - mount_switch.set_active(mount.active) - mount_switch.set_sensitive(mount.managed and not mount.needs_upgrade) - if mount.managed and mount.managed_record is not None: - if mount.needs_upgrade: - mount_switch.set_tooltip_text("Upgrade this older mount before enabling it") - else: - mount_switch.set_tooltip_text("Enable or disable on-demand access for this managed mount") - mount_switch.connect( - "notify::active", - lambda switch, _param: self.toggle_mount(mount.managed_record, switch), - ) - else: - mount_switch.set_tooltip_text("This SMB mount is not managed by this app") - - text_box = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=3) - text_box.set_hexpand(True) - - source_label = Gtk.Label(label=mount.source) - source_label.set_xalign(0) - source_label.add_css_class("heading") - source_label.set_ellipsize(Pango.EllipsizeMode.END) - - detail = f"{mount.mount_point} - {mount.status}" - detail_label = Gtk.Label(label=detail) - detail_label.set_xalign(0) - detail_label.add_css_class("dim-label") - detail_label.set_ellipsize(Pango.EllipsizeMode.END) - - text_box.append(source_label) - text_box.append(detail_label) - - box.append(mount_switch) - box.append(text_box) - - if mount.managed and mount.managed_record is not None: - if mount.needs_upgrade: - upgrade_button = Gtk.Button(label="Upgrade") - upgrade_button.set_tooltip_text("Upgrade mount units using the existing encrypted credentials") - upgrade_button.add_css_class("upgrade-action") - upgrade_button.connect("clicked", lambda _button: self.upgrade_mount(mount.managed_record)) - box.append(upgrade_button) - else: - open_button = Gtk.Button.new_from_icon_name("folder-open-symbolic") - open_button.set_sensitive(mount.openable) - open_button.set_tooltip_text( - "Open mount folder" if mount.openable else "Enable on-demand access to open its folder" - ) - open_button.connect("clicked", lambda _button: self.open_mount_folder(mount.managed_record)) - box.append(open_button) - - delete_button = Gtk.Button.new_from_icon_name("user-trash-symbolic") - delete_button.set_tooltip_text("Delete mount") - delete_button.add_css_class("destructive-action") - delete_button.connect("clicked", lambda _button: self.confirm_delete(mount.managed_record)) - - box.append(delete_button) - else: - not_managed_label = Gtk.Label(label="Not managed") - not_managed_label.add_css_class("dim-label") - not_managed_label.set_valign(Gtk.Align.CENTER) - box.append(not_managed_label) - - row.set_child(box) - return row - - def show_add_dialog(self) -> None: - AddShareWindow(self, self.mount_created).present() - - def show_about_dialog(self) -> None: - dialog = Gtk.AboutDialog() - dialog.set_transient_for(self) - dialog.set_modal(True) - dialog.set_program_name(APP_NAME) - dialog.set_logo_icon_name(APP_ICON_NAME) - dialog.set_comments("Create and manage on-demand SMB mounts.") - dialog.set_authors(APP_DEVELOPERS) - dialog.add_credit_section("Developed by", APP_DEVELOPERS) - dialog.set_website(APP_WEBSITE) - dialog.set_website_label("Project homepage") - dialog.set_license_type(Gtk.License.GPL_3_0_ONLY) - dialog.present() - - def mount_created(self, share: str) -> None: - self.refresh() - MessageWindow(self, "SMB Mount Created", f"{share} will mount when accessed.").present() - - def open_mount_folder(self, record: ManagedMount) -> None: - if not record.mount_point.exists(): - MessageWindow(self, "Open Folder Failed", f"Mount folder does not exist: {record.mount_point}").present() - return - - try: - run_command(["xdg-open", str(record.mount_point)]) - except MountManagerError as exc: - MessageWindow(self, "Open Folder Failed", f"Could not open {record.mount_point}: {exc}").present() - - def upgrade_mount(self, record: ManagedMount) -> None: - try: - request_helper_upgrade(record) - except MountManagerError as exc: - MessageWindow(self, "Upgrade Failed", str(exc)).present() - return - except Exception as exc: - MessageWindow(self, "Upgrade Failed", f"Unexpected error: {exc}").present() - return - - self.refresh() - MessageWindow(self, "SMB Mount Upgraded", f"{record.source} will mount when accessed.").present() - - def toggle_mount(self, record: ManagedMount, switch: Gtk.Switch) -> None: - enabled = switch.get_active() - switch.set_sensitive(False) - try: - request_helper_set_enabled(record, enabled) - except MountManagerError as exc: - MessageWindow(self, "Mount Toggle Failed", str(exc)).present() - except Exception as exc: - MessageWindow(self, "Mount Toggle Failed", f"Unexpected error: {exc}").present() - finally: - self.refresh() - - def confirm_delete(self, record: ManagedMount) -> None: - DeleteMountWindow(self, record, self.refresh).present() - - class MountManagerApplication(Gtk.Application): - def __init__(self) -> None: - super().__init__(application_id=APP_ID, flags=Gio.ApplicationFlags.DEFAULT_FLAGS) - - def do_activate(self) -> None: - window = self.props.active_window - if window is None: - window = MainWindow(self) - window.present() - - app = MountManagerApplication() - return app.run(sys.argv) + from mount_manager_ui import run_gui as _run_gui + return _run_gui() def parse_args(argv: list[str]) -> argparse.Namespace: parser = argparse.ArgumentParser(description=APP_NAME) diff --git a/mount_manager_ui.py b/mount_manager_ui.py new file mode 100644 index 0000000..672fcb5 --- /dev/null +++ b/mount_manager_ui.py @@ -0,0 +1,636 @@ +"""GTK 4 GUI for SMB Mount Manager. + +This module is imported lazily from ``mount_manager.run_gui``. Keeping it +separate from ``mount_manager.py`` lets the helper subprocess avoid importing +GTK when invoked with ``--helper``. +""" + +from __future__ import annotations + +import sys +from typing import Any + +import gi + +gi.require_version("Gdk", "4.0") +gi.require_version("Gtk", "4.0") +gi.require_version("Pango", "1.0") +from gi.repository import Gdk, Gio, Gtk, Pango # noqa: E402 + +from mount_manager import ( + APP_DEVELOPERS, + APP_ICON_NAME, + APP_ID, + APP_NAME, + APP_WEBSITE, + DisplayedMount, + ManagedMount, + MountManagerError, + SharePath, + check_smb_host_reachable, + detect_color_scheme, + load_displayed_mounts, + request_helper_create, + request_helper_delete, + request_helper_set_enabled, + request_helper_upgrade, + run_command, + validate_credentials, +) + + +APP_CSS = """ +window { + background: @theme_bg_color; + color: @theme_fg_color; +} + +headerbar { + background: @theme_base_color; + color: @theme_text_color; +} + +.mount-root { + background: @theme_bg_color; +} + +.boxed-list { + background: @theme_base_color; + color: @theme_text_color; + border: 1px solid alpha(@theme_fg_color, 0.16); + border-radius: 8px; +} + +.boxed-list row { + background: transparent; + color: @theme_text_color; +} + +.boxed-list row:not(:last-child) { + border-bottom: 1px solid alpha(@theme_fg_color, 0.10); +} + +.dim-label { + opacity: 0.72; +} + +.error { + color: #c01c28; +} + +.success { + color: #26a269; +} + +button.headerbar-control, +menubutton.headerbar-control > button { + min-height: 34px; + min-width: 34px; + padding-top: 4px; + padding-bottom: 4px; +} + +button.add-share-button { + font-weight: 700; + padding-left: 12px; + padding-right: 12px; +} + +button.upgrade-action { + background: #26a269; + color: white; +} + +button.upgrade-action:hover { + background: #2ec27e; +} + +button.upgrade-action:active { + background: #1a7f52; +} +""" + + +def apply_theme(Gtk: Any, Gdk: Any) -> None: + settings = Gtk.Settings.get_default() + if settings is not None: + settings.set_property( + "gtk-application-prefer-dark-theme", + detect_color_scheme() == "dark", + ) + + display = Gdk.Display.get_default() + if display is None: + return + + Gtk.Window.set_default_icon_name(APP_ICON_NAME) + + provider = Gtk.CssProvider() + provider.load_from_data(APP_CSS.encode("utf-8")) + Gtk.StyleContext.add_provider_for_display( + display, + provider, + Gtk.STYLE_PROVIDER_PRIORITY_APPLICATION, + ) + + +def run_gui() -> int: + if not Gtk.init_check(): + print( + "GTK could not connect to your graphical session. Run this from your " + "desktop session, not a plain TTY.", + file=sys.stderr, + ) + return 1 + if Gdk.Display.get_default() is None: + print( + "GTK did not provide a usable display. Run this from your desktop " + "session, not a plain TTY.", + file=sys.stderr, + ) + return 1 + apply_theme(Gtk, Gdk) + + class AddShareWindow(Gtk.Window): + def __init__(self, parent: Gtk.Window, on_complete: Any) -> None: + super().__init__(title="Add SMB Share") + self.set_transient_for(parent) + self.set_modal(True) + self.set_default_size(560, -1) + self.set_resizable(False) + self.on_complete = on_complete + self.share_path: SharePath | None = None + + root = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=14) + root.set_margin_top(18) + root.set_margin_bottom(18) + root.set_margin_start(18) + root.set_margin_end(18) + self.set_child(root) + + self.path_box = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=8) + root.append(self.path_box) + + path_label = Gtk.Label(label="Please add share path") + path_label.set_xalign(0) + self.path_box.append(path_label) + + self.path_entry = Gtk.Entry() + self.path_entry.set_placeholder_text("//hostname/share") + self.path_entry.set_hexpand(True) + self.path_entry.connect("activate", lambda _entry: self.on_next_clicked()) + self.path_box.append(self.path_entry) + + path_help = Gtk.Label(label="Example: //192.168.1.2/sharename or //hostname/sharename") + path_help.set_xalign(0) + path_help.add_css_class("dim-label") + self.path_box.append(path_help) + + self.credentials_box = Gtk.Grid(column_spacing=12, row_spacing=10) + self.credentials_box.set_visible(False) + root.append(self.credentials_box) + + host_status_label = Gtk.Label(label="") + host_status_label.set_xalign(0) + host_status_label.add_css_class("success") + self.credentials_box.attach(host_status_label, 0, 0, 2, 1) + self.host_status_label = host_status_label + + user_label = Gtk.Label(label="Username") + user_label.set_xalign(0) + self.credentials_box.attach(user_label, 0, 1, 1, 1) + + self.user_entry = Gtk.Entry() + self.user_entry.set_hexpand(True) + self.user_entry.connect("activate", lambda _entry: self.password_entry.grab_focus()) + self.credentials_box.attach(self.user_entry, 1, 1, 1, 1) + + password_label = Gtk.Label(label="Password") + password_label.set_xalign(0) + self.credentials_box.attach(password_label, 0, 2, 1, 1) + + self.password_entry = Gtk.PasswordEntry() + self.password_entry.set_hexpand(True) + self.password_entry.connect("activate", lambda _entry: self.on_next_clicked()) + self.credentials_box.attach(self.password_entry, 1, 2, 1, 1) + + self.status_label = Gtk.Label() + self.status_label.set_xalign(0) + self.status_label.set_wrap(True) + self.status_label.add_css_class("dim-label") + self.status_label.set_visible(False) + root.append(self.status_label) + + buttons = Gtk.Box(orientation=Gtk.Orientation.HORIZONTAL, spacing=8) + buttons.set_halign(Gtk.Align.END) + root.append(buttons) + + cancel_button = Gtk.Button(label="Cancel") + cancel_button.connect("clicked", lambda _button: self.close()) + buttons.append(cancel_button) + + self.back_button = Gtk.Button(label="Back") + self.back_button.set_visible(False) + self.back_button.connect("clicked", lambda _button: self.show_path_step()) + buttons.append(self.back_button) + + self.next_button = Gtk.Button(label="Check host") + self.next_button.add_css_class("suggested-action") + self.next_button.connect("clicked", lambda _button: self.on_next_clicked()) + buttons.append(self.next_button) + + self.path_entry.grab_focus() + + def set_status(self, message: str, css_class: str) -> None: + self.status_label.remove_css_class("error") + self.status_label.remove_css_class("success") + self.status_label.add_css_class(css_class) + self.status_label.set_text(message) + self.status_label.set_visible(True) + + def show_path_step(self) -> None: + self.share_path = None + self.path_entry.set_sensitive(True) + self.path_box.set_visible(True) + self.credentials_box.set_visible(False) + self.back_button.set_visible(False) + self.next_button.set_label("Check host") + self.status_label.set_visible(False) + self.path_entry.grab_focus() + + def show_credentials_step(self, share_path: SharePath) -> None: + self.share_path = share_path + self.path_entry.set_sensitive(False) + self.path_box.set_visible(True) + self.credentials_box.set_visible(True) + self.host_status_label.set_text("Host is reachable. Please enter credentials.") + self.back_button.set_visible(True) + self.next_button.set_label("Create") + self.status_label.set_visible(False) + self.user_entry.grab_focus() + + def on_next_clicked(self) -> None: + if self.share_path is None: + self.check_host() + else: + self.create_share() + + def check_host(self) -> None: + try: + share_path = check_smb_host_reachable(self.path_entry.get_text()) + except MountManagerError as exc: + self.set_status(str(exc), "error") + return + except Exception as exc: + self.set_status(f"Unexpected error: {exc}", "error") + return + + self.show_credentials_step(share_path) + + def create_share(self) -> None: + if self.share_path is None: + self.set_status("Check the share path before entering credentials.", "error") + return + + share = self.share_path.source + username = self.user_entry.get_text() + password = self.password_entry.get_text() + + try: + validate_credentials(username, password) + self.set_status("Creating encrypted on-demand mount...", "success") + request_helper_create(share, username, password) + except MountManagerError as exc: + self.set_status(str(exc), "error") + return + except Exception as exc: + self.set_status(f"Unexpected error: {exc}", "error") + return + + self.close() + self.on_complete(share) + + class MessageWindow(Gtk.Window): + def __init__(self, parent: Gtk.Window, title: str, message: str) -> None: + super().__init__(title=title) + self.set_transient_for(parent) + self.set_modal(True) + self.set_default_size(420, -1) + self.set_resizable(False) + + root = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=14) + root.set_margin_top(18) + root.set_margin_bottom(18) + root.set_margin_start(18) + root.set_margin_end(18) + self.set_child(root) + + heading = Gtk.Label(label=title) + heading.add_css_class("title-3") + heading.set_xalign(0) + root.append(heading) + + label = Gtk.Label(label=message) + label.set_wrap(True) + label.set_xalign(0) + root.append(label) + + buttons = Gtk.Box(orientation=Gtk.Orientation.HORIZONTAL, spacing=8) + buttons.set_halign(Gtk.Align.END) + root.append(buttons) + + ok_button = Gtk.Button(label="OK") + ok_button.add_css_class("suggested-action") + ok_button.connect("clicked", lambda _button: self.close()) + buttons.append(ok_button) + + class DeleteMountWindow(Gtk.Window): + def __init__(self, parent: Gtk.Window, record: ManagedMount, on_complete: Any) -> None: + super().__init__(title="Delete SMB Mount") + self.set_transient_for(parent) + self.set_modal(True) + self.set_default_size(460, -1) + self.set_resizable(False) + self.record = record + self.on_complete = on_complete + + root = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=14) + root.set_margin_top(18) + root.set_margin_bottom(18) + root.set_margin_start(18) + root.set_margin_end(18) + self.set_child(root) + + heading = Gtk.Label(label="Delete SMB Mount") + heading.add_css_class("title-3") + heading.set_xalign(0) + root.append(heading) + + label = Gtk.Label(label=f"Delete {record.source} and remove its systemd units?") + label.set_wrap(True) + label.set_xalign(0) + root.append(label) + + self.error_label = Gtk.Label() + self.error_label.set_xalign(0) + self.error_label.set_wrap(True) + self.error_label.add_css_class("error") + self.error_label.set_visible(False) + root.append(self.error_label) + + buttons = Gtk.Box(orientation=Gtk.Orientation.HORIZONTAL, spacing=8) + buttons.set_halign(Gtk.Align.END) + root.append(buttons) + + cancel_button = Gtk.Button(label="Cancel") + cancel_button.connect("clicked", lambda _button: self.close()) + buttons.append(cancel_button) + + delete_button = Gtk.Button(label="Delete") + delete_button.add_css_class("destructive-action") + delete_button.connect("clicked", lambda _button: self.delete_share()) + buttons.append(delete_button) + + def show_error(self, message: str) -> None: + self.error_label.set_text(message) + self.error_label.set_visible(True) + + def delete_share(self) -> None: + try: + request_helper_delete(self.record) + except MountManagerError as exc: + self.show_error(str(exc)) + return + except Exception as exc: + self.show_error(f"Unexpected error: {exc}") + return + + self.close() + self.on_complete() + + class MainWindow(Gtk.ApplicationWindow): + def __init__(self, app: Gtk.Application) -> None: + super().__init__(application=app, title=APP_NAME) + self.set_default_size(760, 480) + self.set_icon_name(APP_ICON_NAME) + + header = Gtk.HeaderBar() + title = Gtk.Label(label=APP_NAME) + title.add_css_class("heading") + header.set_title_widget(title) + + refresh_button = Gtk.Button.new_from_icon_name("view-refresh-symbolic") + refresh_button.set_tooltip_text("Refresh") + refresh_button.add_css_class("headerbar-control") + refresh_button.connect("clicked", lambda _button: self.refresh()) + + about_action = Gio.SimpleAction.new("about", None) + about_action.connect("activate", lambda _action, _param: self.show_about_dialog()) + self.add_action(about_action) + + menu = Gio.Menu() + menu.append(f"About {APP_NAME}", "win.about") + + menu_button = Gtk.MenuButton() + menu_button.set_icon_name("open-menu-symbolic") + menu_button.set_menu_model(menu) + menu_button.set_tooltip_text("Main menu") + menu_button.add_css_class("headerbar-control") + + add_button = Gtk.Button(label="ADD SHARE") + add_button.set_tooltip_text("Add share") + add_button.add_css_class("suggested-action") + add_button.add_css_class("headerbar-control") + add_button.add_css_class("add-share-button") + add_button.connect("clicked", lambda _button: self.show_add_dialog()) + header.pack_start(add_button) + header.pack_end(menu_button) + header.pack_end(refresh_button) + + self.set_titlebar(header) + + root = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=12) + root.add_css_class("mount-root") + root.set_margin_top(16) + root.set_margin_bottom(16) + root.set_margin_start(16) + root.set_margin_end(16) + self.set_child(root) + + self.empty_label = Gtk.Label(label="No SMB mounts found.") + self.empty_label.add_css_class("dim-label") + self.empty_label.set_margin_top(32) + + self.list_box = Gtk.ListBox() + self.list_box.set_selection_mode(Gtk.SelectionMode.NONE) + self.list_box.add_css_class("boxed-list") + + scroller = Gtk.ScrolledWindow() + scroller.set_policy(Gtk.PolicyType.NEVER, Gtk.PolicyType.AUTOMATIC) + scroller.set_child(self.list_box) + scroller.set_vexpand(True) + root.append(scroller) + root.append(self.empty_label) + + self.refresh() + + def refresh(self) -> None: + while True: + row = self.list_box.get_first_child() + if row is None: + break + self.list_box.remove(row) + + mounts = load_displayed_mounts() + self.empty_label.set_visible(not mounts) + self.list_box.set_visible(bool(mounts)) + + for mount in mounts: + self.list_box.append(self.row_for(mount)) + + def row_for(self, mount: DisplayedMount) -> Gtk.ListBoxRow: + row = Gtk.ListBoxRow() + box = Gtk.Box(orientation=Gtk.Orientation.HORIZONTAL, spacing=12) + box.set_margin_top(10) + box.set_margin_bottom(10) + box.set_margin_start(12) + box.set_margin_end(12) + + mount_switch = Gtk.Switch() + mount_switch.set_valign(Gtk.Align.CENTER) + mount_switch.set_active(mount.active) + mount_switch.set_sensitive(mount.managed and not mount.needs_upgrade) + if mount.managed and mount.managed_record is not None: + if mount.needs_upgrade: + mount_switch.set_tooltip_text("Upgrade this older mount before enabling it") + else: + mount_switch.set_tooltip_text("Enable or disable on-demand access for this managed mount") + mount_switch.connect( + "notify::active", + lambda switch, _param: self.toggle_mount(mount.managed_record, switch), + ) + else: + mount_switch.set_tooltip_text("This SMB mount is not managed by this app") + + text_box = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=3) + text_box.set_hexpand(True) + + source_label = Gtk.Label(label=mount.source) + source_label.set_xalign(0) + source_label.add_css_class("heading") + source_label.set_ellipsize(Pango.EllipsizeMode.END) + + detail = f"{mount.mount_point} - {mount.status}" + detail_label = Gtk.Label(label=detail) + detail_label.set_xalign(0) + detail_label.add_css_class("dim-label") + detail_label.set_ellipsize(Pango.EllipsizeMode.END) + + text_box.append(source_label) + text_box.append(detail_label) + + box.append(mount_switch) + box.append(text_box) + + if mount.managed and mount.managed_record is not None: + if mount.needs_upgrade: + upgrade_button = Gtk.Button(label="Upgrade") + upgrade_button.set_tooltip_text("Upgrade mount units using the existing encrypted credentials") + upgrade_button.add_css_class("upgrade-action") + upgrade_button.connect("clicked", lambda _button: self.upgrade_mount(mount.managed_record)) + box.append(upgrade_button) + else: + open_button = Gtk.Button.new_from_icon_name("folder-open-symbolic") + open_button.set_sensitive(mount.openable) + open_button.set_tooltip_text( + "Open mount folder" if mount.openable else "Enable on-demand access to open its folder" + ) + open_button.connect("clicked", lambda _button: self.open_mount_folder(mount.managed_record)) + box.append(open_button) + + delete_button = Gtk.Button.new_from_icon_name("user-trash-symbolic") + delete_button.set_tooltip_text("Delete mount") + delete_button.add_css_class("destructive-action") + delete_button.connect("clicked", lambda _button: self.confirm_delete(mount.managed_record)) + + box.append(delete_button) + else: + not_managed_label = Gtk.Label(label="Not managed") + not_managed_label.add_css_class("dim-label") + not_managed_label.set_valign(Gtk.Align.CENTER) + box.append(not_managed_label) + + row.set_child(box) + return row + + def show_add_dialog(self) -> None: + AddShareWindow(self, self.mount_created).present() + + def show_about_dialog(self) -> None: + dialog = Gtk.AboutDialog() + dialog.set_transient_for(self) + dialog.set_modal(True) + dialog.set_program_name(APP_NAME) + dialog.set_logo_icon_name(APP_ICON_NAME) + dialog.set_comments("Create and manage on-demand SMB mounts.") + dialog.set_authors(APP_DEVELOPERS) + dialog.add_credit_section("Developed by", APP_DEVELOPERS) + dialog.set_website(APP_WEBSITE) + dialog.set_website_label("Project homepage") + dialog.set_license_type(Gtk.License.GPL_3_0_ONLY) + dialog.present() + + def mount_created(self, share: str) -> None: + self.refresh() + MessageWindow(self, "SMB Mount Created", f"{share} will mount when accessed.").present() + + def open_mount_folder(self, record: ManagedMount) -> None: + if not record.mount_point.exists(): + MessageWindow(self, "Open Folder Failed", f"Mount folder does not exist: {record.mount_point}").present() + return + + try: + run_command(["xdg-open", str(record.mount_point)]) + except MountManagerError as exc: + MessageWindow(self, "Open Folder Failed", f"Could not open {record.mount_point}: {exc}").present() + + def upgrade_mount(self, record: ManagedMount) -> None: + try: + request_helper_upgrade(record) + except MountManagerError as exc: + MessageWindow(self, "Upgrade Failed", str(exc)).present() + return + except Exception as exc: + MessageWindow(self, "Upgrade Failed", f"Unexpected error: {exc}").present() + return + + self.refresh() + MessageWindow(self, "SMB Mount Upgraded", f"{record.source} will mount when accessed.").present() + + def toggle_mount(self, record: ManagedMount, switch: Gtk.Switch) -> None: + enabled = switch.get_active() + switch.set_sensitive(False) + try: + request_helper_set_enabled(record, enabled) + except MountManagerError as exc: + MessageWindow(self, "Mount Toggle Failed", str(exc)).present() + except Exception as exc: + MessageWindow(self, "Mount Toggle Failed", f"Unexpected error: {exc}").present() + finally: + self.refresh() + + def confirm_delete(self, record: ManagedMount) -> None: + DeleteMountWindow(self, record, self.refresh).present() + + class MountManagerApplication(Gtk.Application): + def __init__(self) -> None: + super().__init__(application_id=APP_ID, flags=Gio.ApplicationFlags.DEFAULT_FLAGS) + + def do_activate(self) -> None: + window = self.props.active_window + if window is None: + window = MainWindow(self) + window.present() + + app = MountManagerApplication() + return app.run(sys.argv) From fe9a8610aed9c3a5b480e55680200ef6df90a590 Mon Sep 17 00:00:00 2001 From: meowtypes Date: Thu, 28 May 2026 03:18:59 -0700 Subject: [PATCH 05/41] feat(ui): switch to Adw.Application and Adw.StyleManager --- mount_manager_ui.py | 112 ++++++++------------------------------------ 1 file changed, 19 insertions(+), 93 deletions(-) diff --git a/mount_manager_ui.py b/mount_manager_ui.py index 672fcb5..72c155c 100644 --- a/mount_manager_ui.py +++ b/mount_manager_ui.py @@ -12,10 +12,11 @@ import gi +gi.require_version("Adw", "1") gi.require_version("Gdk", "4.0") gi.require_version("Gtk", "4.0") gi.require_version("Pango", "1.0") -from gi.repository import Gdk, Gio, Gtk, Pango # noqa: E402 +from gi.repository import Adw, Gdk, Gio, Gtk, Pango # noqa: E402 from mount_manager import ( APP_DEVELOPERS, @@ -23,12 +24,13 @@ APP_ID, APP_NAME, APP_WEBSITE, + MIN_LIBADWAITA_VERSION, DisplayedMount, ManagedMount, MountManagerError, SharePath, + _libadwaita_supports, check_smb_host_reachable, - detect_color_scheme, load_displayed_mounts, request_helper_create, request_helper_delete, @@ -39,102 +41,26 @@ ) -APP_CSS = """ -window { - background: @theme_bg_color; - color: @theme_fg_color; -} - -headerbar { - background: @theme_base_color; - color: @theme_text_color; -} - -.mount-root { - background: @theme_bg_color; -} - -.boxed-list { - background: @theme_base_color; - color: @theme_text_color; - border: 1px solid alpha(@theme_fg_color, 0.16); - border-radius: 8px; -} - -.boxed-list row { - background: transparent; - color: @theme_text_color; -} - -.boxed-list row:not(:last-child) { - border-bottom: 1px solid alpha(@theme_fg_color, 0.10); -} - -.dim-label { - opacity: 0.72; -} - -.error { - color: #c01c28; -} - -.success { - color: #26a269; -} - -button.headerbar-control, -menubutton.headerbar-control > button { - min-height: 34px; - min-width: 34px; - padding-top: 4px; - padding-bottom: 4px; -} - -button.add-share-button { - font-weight: 700; - padding-left: 12px; - padding-right: 12px; -} - -button.upgrade-action { - background: #26a269; - color: white; -} - -button.upgrade-action:hover { - background: #2ec27e; -} - -button.upgrade-action:active { - background: #1a7f52; -} -""" - - -def apply_theme(Gtk: Any, Gdk: Any) -> None: - settings = Gtk.Settings.get_default() - if settings is not None: - settings.set_property( - "gtk-application-prefer-dark-theme", - detect_color_scheme() == "dark", +def ensure_libadwaita_supported() -> None: + """Print an error and raise SystemExit if libadwaita is too old.""" + if not _libadwaita_supports(Adw.MAJOR_VERSION, Adw.MINOR_VERSION): + required = ".".join(str(v) for v in MIN_LIBADWAITA_VERSION) + found = f"{Adw.MAJOR_VERSION}.{Adw.MINOR_VERSION}" + print( + f"libadwaita {found} found, but this app requires {required} or newer.", + file=sys.stderr, ) + raise SystemExit(1) - display = Gdk.Display.get_default() - if display is None: - return +def apply_style_manager() -> None: + """Hand color-scheme selection to libadwaita's system preference tracker.""" + Adw.StyleManager.get_default().set_color_scheme(Adw.ColorScheme.DEFAULT) Gtk.Window.set_default_icon_name(APP_ICON_NAME) - provider = Gtk.CssProvider() - provider.load_from_data(APP_CSS.encode("utf-8")) - Gtk.StyleContext.add_provider_for_display( - display, - provider, - Gtk.STYLE_PROVIDER_PRIORITY_APPLICATION, - ) - def run_gui() -> int: + ensure_libadwaita_supported() if not Gtk.init_check(): print( "GTK could not connect to your graphical session. Run this from your " @@ -149,7 +75,7 @@ def run_gui() -> int: file=sys.stderr, ) return 1 - apply_theme(Gtk, Gdk) + apply_style_manager() class AddShareWindow(Gtk.Window): def __init__(self, parent: Gtk.Window, on_complete: Any) -> None: @@ -622,7 +548,7 @@ def toggle_mount(self, record: ManagedMount, switch: Gtk.Switch) -> None: def confirm_delete(self, record: ManagedMount) -> None: DeleteMountWindow(self, record, self.refresh).present() - class MountManagerApplication(Gtk.Application): + class MountManagerApplication(Adw.Application): def __init__(self) -> None: super().__init__(application_id=APP_ID, flags=Gio.ApplicationFlags.DEFAULT_FLAGS) From 2100d0282aaf589ae3faad9be1eb903927c48ede Mon Sep 17 00:00:00 2001 From: meowtypes Date: Thu, 28 May 2026 03:23:24 -0700 Subject: [PATCH 06/41] feat(ui): adopt Adw.ApplicationWindow with ToolbarView and ToastOverlay --- mount_manager_ui.py | 61 +++++++++++++++++++++++---------------------- 1 file changed, 31 insertions(+), 30 deletions(-) diff --git a/mount_manager_ui.py b/mount_manager_ui.py index 72c155c..90fe951 100644 --- a/mount_manager_ui.py +++ b/mount_manager_ui.py @@ -334,54 +334,42 @@ def delete_share(self) -> None: self.close() self.on_complete() - class MainWindow(Gtk.ApplicationWindow): - def __init__(self, app: Gtk.Application) -> None: + class MainWindow(Adw.ApplicationWindow): + def __init__(self, app: Adw.Application) -> None: super().__init__(application=app, title=APP_NAME) self.set_default_size(760, 480) self.set_icon_name(APP_ICON_NAME) - header = Gtk.HeaderBar() - title = Gtk.Label(label=APP_NAME) - title.add_css_class("heading") - header.set_title_widget(title) - - refresh_button = Gtk.Button.new_from_icon_name("view-refresh-symbolic") - refresh_button.set_tooltip_text("Refresh") - refresh_button.add_css_class("headerbar-control") - refresh_button.connect("clicked", lambda _button: self.refresh()) - about_action = Gio.SimpleAction.new("about", None) - about_action.connect("activate", lambda _action, _param: self.show_about_dialog()) + about_action.connect("activate", lambda _a, _p: self.show_about_dialog()) self.add_action(about_action) menu = Gio.Menu() menu.append(f"About {APP_NAME}", "win.about") - menu_button = Gtk.MenuButton() - menu_button.set_icon_name("open-menu-symbolic") + menu_button = Gtk.MenuButton(icon_name="open-menu-symbolic") menu_button.set_menu_model(menu) menu_button.set_tooltip_text("Main menu") - menu_button.add_css_class("headerbar-control") - add_button = Gtk.Button(label="ADD SHARE") + refresh_button = Gtk.Button.new_from_icon_name("view-refresh-symbolic") + refresh_button.set_tooltip_text("Refresh") + refresh_button.connect("clicked", lambda _b: self.refresh()) + + add_button = Gtk.Button(label="Add Share") add_button.set_tooltip_text("Add share") add_button.add_css_class("suggested-action") - add_button.add_css_class("headerbar-control") - add_button.add_css_class("add-share-button") - add_button.connect("clicked", lambda _button: self.show_add_dialog()) + add_button.connect("clicked", lambda _b: self.show_add_dialog()) + + header = Adw.HeaderBar() header.pack_start(add_button) header.pack_end(menu_button) header.pack_end(refresh_button) - self.set_titlebar(header) + self.toast_overlay = Adw.ToastOverlay() - root = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=12) - root.add_css_class("mount-root") - root.set_margin_top(16) - root.set_margin_bottom(16) - root.set_margin_start(16) - root.set_margin_end(16) - self.set_child(root) + # Content area; Tasks 6-8 replace the list/empty children inside it. + self.content_box = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=0) + self.toast_overlay.set_child(self.content_box) self.empty_label = Gtk.Label(label="No SMB mounts found.") self.empty_label.add_css_class("dim-label") @@ -395,11 +383,24 @@ def __init__(self, app: Gtk.Application) -> None: scroller.set_policy(Gtk.PolicyType.NEVER, Gtk.PolicyType.AUTOMATIC) scroller.set_child(self.list_box) scroller.set_vexpand(True) - root.append(scroller) - root.append(self.empty_label) + scroller.set_margin_top(16) + scroller.set_margin_bottom(16) + scroller.set_margin_start(16) + scroller.set_margin_end(16) + + self.content_box.append(scroller) + self.content_box.append(self.empty_label) + + toolbar_view = Adw.ToolbarView() + toolbar_view.add_top_bar(header) + toolbar_view.set_content(self.toast_overlay) + self.set_content(toolbar_view) self.refresh() + def show_toast(self, message: str) -> None: + self.toast_overlay.add_toast(Adw.Toast(title=message)) + def refresh(self) -> None: while True: row = self.list_box.get_first_child() From 342285db709d67d25edec26da773f3572ab25d7e Mon Sep 17 00:00:00 2001 From: meowtypes Date: Thu, 28 May 2026 03:30:45 -0700 Subject: [PATCH 07/41] feat(ui): add mount_status_line helper --- mount_manager_ui.py | 5 ++++ tests/test_mount_status_line.py | 51 +++++++++++++++++++++++++++++++++ 2 files changed, 56 insertions(+) create mode 100644 tests/test_mount_status_line.py diff --git a/mount_manager_ui.py b/mount_manager_ui.py index 90fe951..313da64 100644 --- a/mount_manager_ui.py +++ b/mount_manager_ui.py @@ -59,6 +59,11 @@ def apply_style_manager() -> None: Gtk.Window.set_default_icon_name(APP_ICON_NAME) +def mount_status_line(mount: DisplayedMount) -> str: + """Build the AdwActionRow subtitle for a mount: `` · ``.""" + return f"{mount.mount_point} · {mount.status}" + + def run_gui() -> int: ensure_libadwaita_supported() if not Gtk.init_check(): diff --git a/tests/test_mount_status_line.py b/tests/test_mount_status_line.py new file mode 100644 index 0000000..b4e15aa --- /dev/null +++ b/tests/test_mount_status_line.py @@ -0,0 +1,51 @@ +"""Unit tests for the AdwActionRow subtitle builder.""" + +import unittest +from pathlib import Path + +from mount_manager import DisplayedMount + + +def _mount(**overrides: object) -> DisplayedMount: + defaults = dict( + source="//host/share", + mount_point=Path("/mnt/mount-manager/share"), + status="Mounted", + active=True, + openable=True, + needs_upgrade=False, + managed=True, + managed_record=None, + ) + defaults.update(overrides) + return DisplayedMount(**defaults) # type: ignore[arg-type] + + +class MountStatusLineTest(unittest.TestCase): + def test_combines_mount_point_and_status(self) -> None: + from mount_manager_ui import mount_status_line + + line = mount_status_line(_mount(status="Mounted")) + self.assertEqual(line, "/mnt/mount-manager/share · Mounted") + + def test_idle_status(self) -> None: + from mount_manager_ui import mount_status_line + + line = mount_status_line(_mount(status="Idle", active=False)) + self.assertEqual(line, "/mnt/mount-manager/share · Idle") + + def test_unmanaged_uses_unmanaged_status(self) -> None: + from mount_manager_ui import mount_status_line + + line = mount_status_line( + _mount( + mount_point=Path("/mnt/elsewhere"), + status="Mounted (not managed)", + managed=False, + ) + ) + self.assertEqual(line, "/mnt/elsewhere · Mounted (not managed)") + + +if __name__ == "__main__": + unittest.main() From 9e1f24210c858d55baff16eb94ca55ee242089d8 Mon Sep 17 00:00:00 2001 From: meowtypes Date: Thu, 28 May 2026 03:34:57 -0700 Subject: [PATCH 08/41] feat(ui): render mounts as AdwPreferencesGroup with AdwActionRow --- mount_manager_ui.py | 176 ++++++++++++++++++++++---------------------- 1 file changed, 90 insertions(+), 86 deletions(-) diff --git a/mount_manager_ui.py b/mount_manager_ui.py index 313da64..bc35fac 100644 --- a/mount_manager_ui.py +++ b/mount_manager_ui.py @@ -16,7 +16,16 @@ gi.require_version("Gdk", "4.0") gi.require_version("Gtk", "4.0") gi.require_version("Pango", "1.0") -from gi.repository import Adw, Gdk, Gio, Gtk, Pango # noqa: E402 +from gi.repository import Adw, Gdk, Gio, GLib, Gtk, Pango # noqa: E402 + + +def GLib_markup_escape(text: str) -> str: + """Escape Pango markup characters in row titles/subtitles.""" + return GLib.markup_escape_text(text, -1) + + +def GLib_VariantType(spec: str) -> GLib.VariantType: + return GLib.VariantType.new(spec) from mount_manager import ( APP_DEVELOPERS, @@ -380,20 +389,14 @@ def __init__(self, app: Adw.Application) -> None: self.empty_label.add_css_class("dim-label") self.empty_label.set_margin_top(32) - self.list_box = Gtk.ListBox() - self.list_box.set_selection_mode(Gtk.SelectionMode.NONE) - self.list_box.add_css_class("boxed-list") + self.preferences_page = Adw.PreferencesPage() + self.preferences_page.set_vexpand(True) - scroller = Gtk.ScrolledWindow() - scroller.set_policy(Gtk.PolicyType.NEVER, Gtk.PolicyType.AUTOMATIC) - scroller.set_child(self.list_box) - scroller.set_vexpand(True) - scroller.set_margin_top(16) - scroller.set_margin_bottom(16) - scroller.set_margin_start(16) - scroller.set_margin_end(16) + self.mount_group = Adw.PreferencesGroup() + self.mount_group.set_title("SMB Shares") + self.preferences_page.add(self.mount_group) - self.content_box.append(scroller) + self.content_box.append(self.preferences_page) self.content_box.append(self.empty_label) toolbar_view = Adw.ToolbarView() @@ -407,92 +410,93 @@ def show_toast(self, message: str) -> None: self.toast_overlay.add_toast(Adw.Toast(title=message)) def refresh(self) -> None: - while True: - row = self.list_box.get_first_child() - if row is None: - break - self.list_box.remove(row) + rows_to_remove = [] + row = self.mount_group.get_first_child() + while row is not None: + rows_to_remove.append(row) + row = row.get_next_sibling() + for row in rows_to_remove: + if isinstance(row, Adw.ActionRow): + self.mount_group.remove(row) mounts = load_displayed_mounts() self.empty_label.set_visible(not mounts) - self.list_box.set_visible(bool(mounts)) + self.preferences_page.set_visible(bool(mounts)) for mount in mounts: - self.list_box.append(self.row_for(mount)) + self.mount_group.add(self.row_for(mount)) - def row_for(self, mount: DisplayedMount) -> Gtk.ListBoxRow: - row = Gtk.ListBoxRow() - box = Gtk.Box(orientation=Gtk.Orientation.HORIZONTAL, spacing=12) - box.set_margin_top(10) - box.set_margin_bottom(10) - box.set_margin_start(12) - box.set_margin_end(12) + def row_for(self, mount: DisplayedMount) -> Adw.ActionRow: + row = Adw.ActionRow() + row.set_title(GLib_markup_escape(mount.source)) + row.set_subtitle(GLib_markup_escape(mount_status_line(mount))) + + if not mount.managed or mount.managed_record is None: + not_managed_label = Gtk.Label(label="Not managed") + not_managed_label.add_css_class("dim-label") + not_managed_label.set_valign(Gtk.Align.CENTER) + row.add_suffix(not_managed_label) + return row + + record = mount.managed_record mount_switch = Gtk.Switch() mount_switch.set_valign(Gtk.Align.CENTER) mount_switch.set_active(mount.active) - mount_switch.set_sensitive(mount.managed and not mount.needs_upgrade) - if mount.managed and mount.managed_record is not None: - if mount.needs_upgrade: - mount_switch.set_tooltip_text("Upgrade this older mount before enabling it") - else: - mount_switch.set_tooltip_text("Enable or disable on-demand access for this managed mount") - mount_switch.connect( - "notify::active", - lambda switch, _param: self.toggle_mount(mount.managed_record, switch), - ) + mount_switch.set_sensitive(not mount.needs_upgrade) + if mount.needs_upgrade: + mount_switch.set_tooltip_text("Upgrade this older mount before enabling it") else: - mount_switch.set_tooltip_text("This SMB mount is not managed by this app") - - text_box = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=3) - text_box.set_hexpand(True) - - source_label = Gtk.Label(label=mount.source) - source_label.set_xalign(0) - source_label.add_css_class("heading") - source_label.set_ellipsize(Pango.EllipsizeMode.END) - - detail = f"{mount.mount_point} - {mount.status}" - detail_label = Gtk.Label(label=detail) - detail_label.set_xalign(0) - detail_label.add_css_class("dim-label") - detail_label.set_ellipsize(Pango.EllipsizeMode.END) - - text_box.append(source_label) - text_box.append(detail_label) - - box.append(mount_switch) - box.append(text_box) - - if mount.managed and mount.managed_record is not None: - if mount.needs_upgrade: - upgrade_button = Gtk.Button(label="Upgrade") - upgrade_button.set_tooltip_text("Upgrade mount units using the existing encrypted credentials") - upgrade_button.add_css_class("upgrade-action") - upgrade_button.connect("clicked", lambda _button: self.upgrade_mount(mount.managed_record)) - box.append(upgrade_button) - else: - open_button = Gtk.Button.new_from_icon_name("folder-open-symbolic") - open_button.set_sensitive(mount.openable) - open_button.set_tooltip_text( - "Open mount folder" if mount.openable else "Enable on-demand access to open its folder" - ) - open_button.connect("clicked", lambda _button: self.open_mount_folder(mount.managed_record)) - box.append(open_button) - - delete_button = Gtk.Button.new_from_icon_name("user-trash-symbolic") - delete_button.set_tooltip_text("Delete mount") - delete_button.add_css_class("destructive-action") - delete_button.connect("clicked", lambda _button: self.confirm_delete(mount.managed_record)) - - box.append(delete_button) + mount_switch.set_tooltip_text( + "Enable or disable on-demand access for this managed mount" + ) + mount_switch.connect( + "notify::active", + lambda switch, _param: self.toggle_mount(record, switch), + ) + row.add_suffix(mount_switch) + + if mount.needs_upgrade: + upgrade_button = Gtk.Button(label="Upgrade") + upgrade_button.set_valign(Gtk.Align.CENTER) + upgrade_button.set_tooltip_text( + "Upgrade mount units using the existing encrypted credentials" + ) + upgrade_button.add_css_class("suggested-action") + upgrade_button.connect("clicked", lambda _b: self.upgrade_mount(record)) + row.add_suffix(upgrade_button) else: - not_managed_label = Gtk.Label(label="Not managed") - not_managed_label.add_css_class("dim-label") - not_managed_label.set_valign(Gtk.Align.CENTER) - box.append(not_managed_label) + open_button = Gtk.Button.new_from_icon_name("folder-open-symbolic") + open_button.set_valign(Gtk.Align.CENTER) + open_button.add_css_class("flat") + open_button.set_sensitive(mount.openable) + open_button.set_tooltip_text( + "Open mount folder" + if mount.openable + else "Enable on-demand access to open its folder" + ) + open_button.connect("clicked", lambda _b: self.open_mount_folder(record)) + row.add_suffix(open_button) + + menu = Gio.Menu() + menu.append("Delete\u2026", f"row.delete::{record.manager_id}") + + row_action_group = Gio.SimpleActionGroup() + delete_action = Gio.SimpleAction.new("delete", GLib_VariantType("s")) + delete_action.connect( + "activate", lambda _a, _p, r=record: self.confirm_delete(r) + ) + row_action_group.add_action(delete_action) + row.insert_action_group("row", row_action_group) + + menu_button = Gtk.MenuButton() + menu_button.set_valign(Gtk.Align.CENTER) + menu_button.set_icon_name("view-more-symbolic") + menu_button.add_css_class("flat") + menu_button.set_menu_model(menu) + menu_button.set_tooltip_text("More actions") + row.add_suffix(menu_button) - row.set_child(box) return row def show_add_dialog(self) -> None: From 937c83e99a63e868844aa1b0fc693d357990c537 Mon Sep 17 00:00:00 2001 From: meowtypes Date: Thu, 28 May 2026 03:41:20 -0700 Subject: [PATCH 09/41] fix(ui): correctly clear AdwActionRow children on refresh --- mount_manager_ui.py | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) diff --git a/mount_manager_ui.py b/mount_manager_ui.py index bc35fac..9200b8e 100644 --- a/mount_manager_ui.py +++ b/mount_manager_ui.py @@ -410,14 +410,11 @@ def show_toast(self, message: str) -> None: self.toast_overlay.add_toast(Adw.Toast(title=message)) def refresh(self) -> None: - rows_to_remove = [] - row = self.mount_group.get_first_child() - while row is not None: - rows_to_remove.append(row) - row = row.get_next_sibling() - for row in rows_to_remove: - if isinstance(row, Adw.ActionRow): - self.mount_group.remove(row) + while True: + row = self.mount_group.get_row(0) + if row is None: + break + self.mount_group.remove(row) mounts = load_displayed_mounts() self.empty_label.set_visible(not mounts) From 30548eb294fb6935b3beb272f418d2f86dbc2604 Mon Sep 17 00:00:00 2001 From: meowtypes Date: Thu, 28 May 2026 03:42:48 -0700 Subject: [PATCH 10/41] feat(ui): replace empty label with Adw.StatusPage --- mount_manager_ui.py | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/mount_manager_ui.py b/mount_manager_ui.py index 9200b8e..8a741a4 100644 --- a/mount_manager_ui.py +++ b/mount_manager_ui.py @@ -385,9 +385,18 @@ def __init__(self, app: Adw.Application) -> None: self.content_box = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=0) self.toast_overlay.set_child(self.content_box) - self.empty_label = Gtk.Label(label="No SMB mounts found.") - self.empty_label.add_css_class("dim-label") - self.empty_label.set_margin_top(32) + self.empty_page = Adw.StatusPage() + self.empty_page.set_icon_name("folder-remote-symbolic") + self.empty_page.set_title("No SMB shares") + self.empty_page.set_description("Click Add Share to mount one.") + self.empty_page.set_vexpand(True) + + empty_action = Gtk.Button(label="Add Share") + empty_action.set_halign(Gtk.Align.CENTER) + empty_action.add_css_class("suggested-action") + empty_action.add_css_class("pill") + empty_action.connect("clicked", lambda _b: self.show_add_dialog()) + self.empty_page.set_child(empty_action) self.preferences_page = Adw.PreferencesPage() self.preferences_page.set_vexpand(True) @@ -397,7 +406,7 @@ def __init__(self, app: Adw.Application) -> None: self.preferences_page.add(self.mount_group) self.content_box.append(self.preferences_page) - self.content_box.append(self.empty_label) + self.content_box.append(self.empty_page) toolbar_view = Adw.ToolbarView() toolbar_view.add_top_bar(header) @@ -417,7 +426,7 @@ def refresh(self) -> None: self.mount_group.remove(row) mounts = load_displayed_mounts() - self.empty_label.set_visible(not mounts) + self.empty_page.set_visible(not mounts) self.preferences_page.set_visible(bool(mounts)) for mount in mounts: From cd458dc10e5b242ff56803a84c07a3b1b3f72dd4 Mon Sep 17 00:00:00 2001 From: meowtypes Date: Thu, 28 May 2026 03:46:25 -0700 Subject: [PATCH 11/41] feat(ui): replace AddShareWindow with AdwDialog and progressive reveal --- mount_manager_ui.py | 263 +++++++++++++++++++++----------------------- 1 file changed, 128 insertions(+), 135 deletions(-) diff --git a/mount_manager_ui.py b/mount_manager_ui.py index 8a741a4..eb2dc0d 100644 --- a/mount_manager_ui.py +++ b/mount_manager_ui.py @@ -91,164 +91,161 @@ def run_gui() -> int: return 1 apply_style_manager() - class AddShareWindow(Gtk.Window): - def __init__(self, parent: Gtk.Window, on_complete: Any) -> None: - super().__init__(title="Add SMB Share") - self.set_transient_for(parent) - self.set_modal(True) - self.set_default_size(560, -1) - self.set_resizable(False) - self.on_complete = on_complete + class AddShareDialog(Adw.Dialog): + def __init__(self, main_window: "MainWindow") -> None: + super().__init__() + self.set_title("Add SMB Share") + self.set_content_width(420) + self.main_window = main_window self.share_path: SharePath | None = None + self._debounce_id: int = 0 - root = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=14) - root.set_margin_top(18) - root.set_margin_bottom(18) - root.set_margin_start(18) - root.set_margin_end(18) - self.set_child(root) - - self.path_box = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=8) - root.append(self.path_box) - - path_label = Gtk.Label(label="Please add share path") - path_label.set_xalign(0) - self.path_box.append(path_label) - - self.path_entry = Gtk.Entry() - self.path_entry.set_placeholder_text("//hostname/share") - self.path_entry.set_hexpand(True) - self.path_entry.connect("activate", lambda _entry: self.on_next_clicked()) - self.path_box.append(self.path_entry) - - path_help = Gtk.Label(label="Example: //192.168.1.2/sharename or //hostname/sharename") - path_help.set_xalign(0) - path_help.add_css_class("dim-label") - self.path_box.append(path_help) - - self.credentials_box = Gtk.Grid(column_spacing=12, row_spacing=10) - self.credentials_box.set_visible(False) - root.append(self.credentials_box) - - host_status_label = Gtk.Label(label="") - host_status_label.set_xalign(0) - host_status_label.add_css_class("success") - self.credentials_box.attach(host_status_label, 0, 0, 2, 1) - self.host_status_label = host_status_label - - user_label = Gtk.Label(label="Username") - user_label.set_xalign(0) - self.credentials_box.attach(user_label, 0, 1, 1, 1) - - self.user_entry = Gtk.Entry() - self.user_entry.set_hexpand(True) - self.user_entry.connect("activate", lambda _entry: self.password_entry.grab_focus()) - self.credentials_box.attach(self.user_entry, 1, 1, 1, 1) - - password_label = Gtk.Label(label="Password") - password_label.set_xalign(0) - self.credentials_box.attach(password_label, 0, 2, 1, 1) - - self.password_entry = Gtk.PasswordEntry() - self.password_entry.set_hexpand(True) - self.password_entry.connect("activate", lambda _entry: self.on_next_clicked()) - self.credentials_box.attach(self.password_entry, 1, 2, 1, 1) - - self.status_label = Gtk.Label() - self.status_label.set_xalign(0) - self.status_label.set_wrap(True) - self.status_label.add_css_class("dim-label") - self.status_label.set_visible(False) - root.append(self.status_label) + self.cancel_button = Gtk.Button(label="Cancel") + self.cancel_button.connect("clicked", lambda _b: self.close()) - buttons = Gtk.Box(orientation=Gtk.Orientation.HORIZONTAL, spacing=8) - buttons.set_halign(Gtk.Align.END) - root.append(buttons) + self.add_button = Gtk.Button(label="Add") + self.add_button.add_css_class("suggested-action") + self.add_button.set_sensitive(False) + self.add_button.connect("clicked", lambda _b: self._on_add_clicked()) - cancel_button = Gtk.Button(label="Cancel") - cancel_button.connect("clicked", lambda _button: self.close()) - buttons.append(cancel_button) + header = Adw.HeaderBar() + header.set_show_start_title_buttons(False) + header.set_show_end_title_buttons(False) + header.pack_start(self.cancel_button) + header.pack_end(self.add_button) - self.back_button = Gtk.Button(label="Back") - self.back_button.set_visible(False) - self.back_button.connect("clicked", lambda _button: self.show_path_step()) - buttons.append(self.back_button) + self.banner = Adw.Banner() + self.banner.set_revealed(False) - self.next_button = Gtk.Button(label="Check host") - self.next_button.add_css_class("suggested-action") - self.next_button.connect("clicked", lambda _button: self.on_next_clicked()) - buttons.append(self.next_button) + page = Adw.PreferencesPage() - self.path_entry.grab_focus() + share_group = Adw.PreferencesGroup() + share_group.set_title("Share") + page.add(share_group) - def set_status(self, message: str, css_class: str) -> None: - self.status_label.remove_css_class("error") - self.status_label.remove_css_class("success") - self.status_label.add_css_class(css_class) - self.status_label.set_text(message) - self.status_label.set_visible(True) + self.path_row = Adw.EntryRow() + self.path_row.set_title("Share path") + self.path_row.set_tooltip_text( + "Example: //192.168.1.2/sharename or //hostname/sharename" + ) + self.path_row.connect("changed", lambda _r: self._on_path_changed()) + share_group.add(self.path_row) + + self.host_spinner = Gtk.Spinner() + self.host_spinner.set_valign(Gtk.Align.CENTER) + self.host_spinner.set_visible(False) + self.path_row.add_suffix(self.host_spinner) + + self.host_status_icon = Gtk.Image() + self.host_status_icon.set_valign(Gtk.Align.CENTER) + self.host_status_icon.set_visible(False) + self.path_row.add_suffix(self.host_status_icon) + + self.credentials_group = Adw.PreferencesGroup() + self.credentials_group.set_title("Credentials") + self.credentials_group.set_sensitive(False) + page.add(self.credentials_group) + + self.user_row = Adw.EntryRow() + self.user_row.set_title("Username") + self.user_row.connect("changed", lambda _r: self._update_add_sensitive()) + self.credentials_group.add(self.user_row) + + self.password_row = Adw.PasswordEntryRow() + self.password_row.set_title("Password") + self.password_row.connect("changed", lambda _r: self._update_add_sensitive()) + self.credentials_group.add(self.password_row) + + body = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=0) + body.append(self.banner) + body.append(page) + + toolbar = Adw.ToolbarView() + toolbar.add_top_bar(header) + toolbar.set_content(body) + self.set_child(toolbar) + + def _show_banner(self, message: str) -> None: + self.banner.set_title(message) + self.banner.set_revealed(True) + + def _hide_banner(self) -> None: + self.banner.set_revealed(False) + + def _set_host_status(self, *, ok: bool | None, message: str) -> None: + self.host_spinner.set_visible(False) + self.host_spinner.stop() + if ok is None: + self.host_status_icon.set_visible(False) + self.path_row.set_title("Share path") + return + if ok: + self.host_status_icon.set_from_icon_name("emblem-ok-symbolic") + else: + self.host_status_icon.set_from_icon_name("dialog-error-symbolic") + self.host_status_icon.set_visible(True) + self.host_status_icon.set_tooltip_text(message) - def show_path_step(self) -> None: + def _on_path_changed(self) -> None: self.share_path = None - self.path_entry.set_sensitive(True) - self.path_box.set_visible(True) - self.credentials_box.set_visible(False) - self.back_button.set_visible(False) - self.next_button.set_label("Check host") - self.status_label.set_visible(False) - self.path_entry.grab_focus() - - def show_credentials_step(self, share_path: SharePath) -> None: - self.share_path = share_path - self.path_entry.set_sensitive(False) - self.path_box.set_visible(True) - self.credentials_box.set_visible(True) - self.host_status_label.set_text("Host is reachable. Please enter credentials.") - self.back_button.set_visible(True) - self.next_button.set_label("Create") - self.status_label.set_visible(False) - self.user_entry.grab_focus() - - def on_next_clicked(self) -> None: - if self.share_path is None: - self.check_host() - else: - self.create_share() + self.credentials_group.set_sensitive(False) + self._update_add_sensitive() + self._hide_banner() + self._set_host_status(ok=None, message="") + if self._debounce_id: + GLib.source_remove(self._debounce_id) + self._debounce_id = 0 + text = self.path_row.get_text().strip() + if not text: + return + self._debounce_id = GLib.timeout_add(300, self._run_host_check) - def check_host(self) -> None: + def _run_host_check(self) -> bool: + self._debounce_id = 0 + self.host_spinner.set_visible(True) + self.host_spinner.start() try: - share_path = check_smb_host_reachable(self.path_entry.get_text()) + share_path = check_smb_host_reachable(self.path_row.get_text()) except MountManagerError as exc: - self.set_status(str(exc), "error") - return + self._set_host_status(ok=False, message=str(exc)) + return False except Exception as exc: - self.set_status(f"Unexpected error: {exc}", "error") - return + self._set_host_status(ok=False, message=f"Unexpected error: {exc}") + return False - self.show_credentials_step(share_path) + self.share_path = share_path + self._set_host_status(ok=True, message="Host is reachable") + self.credentials_group.set_sensitive(True) + self._update_add_sensitive() + return False # don't repeat the timeout + + def _update_add_sensitive(self) -> None: + ready = ( + self.share_path is not None + and bool(self.user_row.get_text().strip()) + and bool(self.password_row.get_text()) + ) + self.add_button.set_sensitive(ready) - def create_share(self) -> None: + def _on_add_clicked(self) -> None: if self.share_path is None: - self.set_status("Check the share path before entering credentials.", "error") return - share = self.share_path.source - username = self.user_entry.get_text() - password = self.password_entry.get_text() - + username = self.user_row.get_text() + password = self.password_row.get_text() try: validate_credentials(username, password) - self.set_status("Creating encrypted on-demand mount...", "success") request_helper_create(share, username, password) except MountManagerError as exc: - self.set_status(str(exc), "error") + self._show_banner(str(exc)) return except Exception as exc: - self.set_status(f"Unexpected error: {exc}", "error") + self._show_banner(f"Unexpected error: {exc}") return self.close() - self.on_complete(share) + self.main_window.refresh() + self.main_window.show_toast(f"{share} will mount when accessed.") class MessageWindow(Gtk.Window): def __init__(self, parent: Gtk.Window, title: str, message: str) -> None: @@ -506,7 +503,7 @@ def row_for(self, mount: DisplayedMount) -> Adw.ActionRow: return row def show_add_dialog(self) -> None: - AddShareWindow(self, self.mount_created).present() + AddShareDialog(self).present(self) def show_about_dialog(self) -> None: dialog = Gtk.AboutDialog() @@ -522,10 +519,6 @@ def show_about_dialog(self) -> None: dialog.set_license_type(Gtk.License.GPL_3_0_ONLY) dialog.present() - def mount_created(self, share: str) -> None: - self.refresh() - MessageWindow(self, "SMB Mount Created", f"{share} will mount when accessed.").present() - def open_mount_folder(self, record: ManagedMount) -> None: if not record.mount_point.exists(): MessageWindow(self, "Open Folder Failed", f"Mount folder does not exist: {record.mount_point}").present() From 8fb7724847a933ba88bf0910541c556a1f95616f Mon Sep 17 00:00:00 2001 From: meowtypes Date: Thu, 28 May 2026 03:50:10 -0700 Subject: [PATCH 12/41] fix(ui): cancel AddShareDialog debounce timer on close --- mount_manager_ui.py | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/mount_manager_ui.py b/mount_manager_ui.py index eb2dc0d..ffb615e 100644 --- a/mount_manager_ui.py +++ b/mount_manager_ui.py @@ -164,6 +164,13 @@ def __init__(self, main_window: "MainWindow") -> None: toolbar.add_top_bar(header) toolbar.set_content(body) self.set_child(toolbar) + + self.connect("closed", self._cleanup) + + def _cleanup(self, *_args) -> None: + if self._debounce_id: + GLib.source_remove(self._debounce_id) + self._debounce_id = 0 def _show_banner(self, message: str) -> None: self.banner.set_title(message) From e090f9bede246e3e8f199bd844b8f3137532176f Mon Sep 17 00:00:00 2001 From: meowtypes Date: Thu, 28 May 2026 03:51:51 -0700 Subject: [PATCH 13/41] feat(ui): replace DeleteMountWindow with Adw.AlertDialog --- mount_manager_ui.py | 97 +++++++++++++++------------------------------ 1 file changed, 32 insertions(+), 65 deletions(-) diff --git a/mount_manager_ui.py b/mount_manager_ui.py index ffb615e..759dae5 100644 --- a/mount_manager_ui.py +++ b/mount_manager_ui.py @@ -288,70 +288,6 @@ def __init__(self, parent: Gtk.Window, title: str, message: str) -> None: ok_button.connect("clicked", lambda _button: self.close()) buttons.append(ok_button) - class DeleteMountWindow(Gtk.Window): - def __init__(self, parent: Gtk.Window, record: ManagedMount, on_complete: Any) -> None: - super().__init__(title="Delete SMB Mount") - self.set_transient_for(parent) - self.set_modal(True) - self.set_default_size(460, -1) - self.set_resizable(False) - self.record = record - self.on_complete = on_complete - - root = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=14) - root.set_margin_top(18) - root.set_margin_bottom(18) - root.set_margin_start(18) - root.set_margin_end(18) - self.set_child(root) - - heading = Gtk.Label(label="Delete SMB Mount") - heading.add_css_class("title-3") - heading.set_xalign(0) - root.append(heading) - - label = Gtk.Label(label=f"Delete {record.source} and remove its systemd units?") - label.set_wrap(True) - label.set_xalign(0) - root.append(label) - - self.error_label = Gtk.Label() - self.error_label.set_xalign(0) - self.error_label.set_wrap(True) - self.error_label.add_css_class("error") - self.error_label.set_visible(False) - root.append(self.error_label) - - buttons = Gtk.Box(orientation=Gtk.Orientation.HORIZONTAL, spacing=8) - buttons.set_halign(Gtk.Align.END) - root.append(buttons) - - cancel_button = Gtk.Button(label="Cancel") - cancel_button.connect("clicked", lambda _button: self.close()) - buttons.append(cancel_button) - - delete_button = Gtk.Button(label="Delete") - delete_button.add_css_class("destructive-action") - delete_button.connect("clicked", lambda _button: self.delete_share()) - buttons.append(delete_button) - - def show_error(self, message: str) -> None: - self.error_label.set_text(message) - self.error_label.set_visible(True) - - def delete_share(self) -> None: - try: - request_helper_delete(self.record) - except MountManagerError as exc: - self.show_error(str(exc)) - return - except Exception as exc: - self.show_error(f"Unexpected error: {exc}") - return - - self.close() - self.on_complete() - class MainWindow(Adw.ApplicationWindow): def __init__(self, app: Adw.Application) -> None: super().__init__(application=app, title=APP_NAME) @@ -562,7 +498,38 @@ def toggle_mount(self, record: ManagedMount, switch: Gtk.Switch) -> None: self.refresh() def confirm_delete(self, record: ManagedMount) -> None: - DeleteMountWindow(self, record, self.refresh).present() + alert = Adw.AlertDialog( + heading="Delete this SMB mount?", + body=( + f"Removes {record.source} and its systemd units. " + "The encrypted credentials will also be deleted." + ), + ) + alert.add_response("cancel", "Cancel") + alert.add_response("delete", "Delete") + alert.set_response_appearance( + "delete", Adw.ResponseAppearance.DESTRUCTIVE + ) + alert.set_default_response("cancel") + alert.set_close_response("cancel") + alert.connect("response", self._on_delete_response, record) + alert.present(self) + + def _on_delete_response( + self, _alert: Adw.AlertDialog, response: str, record: ManagedMount + ) -> None: + if response != "delete": + return + try: + request_helper_delete(record) + except MountManagerError as exc: + self.show_toast(f"Delete failed: {exc}") + return + except Exception as exc: + self.show_toast(f"Delete failed: {exc}") + return + self.refresh() + self.show_toast(f"{record.source} removed.") class MountManagerApplication(Adw.Application): def __init__(self) -> None: From 74fed38853b20eb6f45a9d6f7ac7ead58928071a Mon Sep 17 00:00:00 2001 From: meowtypes Date: Thu, 28 May 2026 03:53:50 -0700 Subject: [PATCH 14/41] feat(ui): replace MessageWindow with AdwToast notifications --- mount_manager_ui.py | 50 +++++++-------------------------------------- 1 file changed, 7 insertions(+), 43 deletions(-) diff --git a/mount_manager_ui.py b/mount_manager_ui.py index 759dae5..330bc34 100644 --- a/mount_manager_ui.py +++ b/mount_manager_ui.py @@ -254,40 +254,6 @@ def _on_add_clicked(self) -> None: self.main_window.refresh() self.main_window.show_toast(f"{share} will mount when accessed.") - class MessageWindow(Gtk.Window): - def __init__(self, parent: Gtk.Window, title: str, message: str) -> None: - super().__init__(title=title) - self.set_transient_for(parent) - self.set_modal(True) - self.set_default_size(420, -1) - self.set_resizable(False) - - root = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=14) - root.set_margin_top(18) - root.set_margin_bottom(18) - root.set_margin_start(18) - root.set_margin_end(18) - self.set_child(root) - - heading = Gtk.Label(label=title) - heading.add_css_class("title-3") - heading.set_xalign(0) - root.append(heading) - - label = Gtk.Label(label=message) - label.set_wrap(True) - label.set_xalign(0) - root.append(label) - - buttons = Gtk.Box(orientation=Gtk.Orientation.HORIZONTAL, spacing=8) - buttons.set_halign(Gtk.Align.END) - root.append(buttons) - - ok_button = Gtk.Button(label="OK") - ok_button.add_css_class("suggested-action") - ok_button.connect("clicked", lambda _button: self.close()) - buttons.append(ok_button) - class MainWindow(Adw.ApplicationWindow): def __init__(self, app: Adw.Application) -> None: super().__init__(application=app, title=APP_NAME) @@ -464,26 +430,24 @@ def show_about_dialog(self) -> None: def open_mount_folder(self, record: ManagedMount) -> None: if not record.mount_point.exists(): - MessageWindow(self, "Open Folder Failed", f"Mount folder does not exist: {record.mount_point}").present() + self.show_toast(f"Mount folder does not exist: {record.mount_point}") return - try: run_command(["xdg-open", str(record.mount_point)]) except MountManagerError as exc: - MessageWindow(self, "Open Folder Failed", f"Could not open {record.mount_point}: {exc}").present() + self.show_toast(f"Could not open {record.mount_point}: {exc}") def upgrade_mount(self, record: ManagedMount) -> None: try: request_helper_upgrade(record) except MountManagerError as exc: - MessageWindow(self, "Upgrade Failed", str(exc)).present() + self.show_toast(f"Upgrade failed: {exc}") return except Exception as exc: - MessageWindow(self, "Upgrade Failed", f"Unexpected error: {exc}").present() + self.show_toast(f"Upgrade failed: {exc}") return - self.refresh() - MessageWindow(self, "SMB Mount Upgraded", f"{record.source} will mount when accessed.").present() + self.show_toast(f"{record.source} upgraded; will mount when accessed.") def toggle_mount(self, record: ManagedMount, switch: Gtk.Switch) -> None: enabled = switch.get_active() @@ -491,9 +455,9 @@ def toggle_mount(self, record: ManagedMount, switch: Gtk.Switch) -> None: try: request_helper_set_enabled(record, enabled) except MountManagerError as exc: - MessageWindow(self, "Mount Toggle Failed", str(exc)).present() + self.show_toast(f"Toggle failed: {exc}") except Exception as exc: - MessageWindow(self, "Mount Toggle Failed", f"Unexpected error: {exc}").present() + self.show_toast(f"Toggle failed: {exc}") finally: self.refresh() From 8a6ed27f1cc45c57f0459d6e1e58a43a04e9c32c Mon Sep 17 00:00:00 2001 From: meowtypes Date: Thu, 28 May 2026 03:56:14 -0700 Subject: [PATCH 15/41] feat(ui): use Adw.AboutDialog --- mount_manager_ui.py | 23 +++++++++++------------ 1 file changed, 11 insertions(+), 12 deletions(-) diff --git a/mount_manager_ui.py b/mount_manager_ui.py index 330bc34..b3ff147 100644 --- a/mount_manager_ui.py +++ b/mount_manager_ui.py @@ -415,18 +415,17 @@ def show_add_dialog(self) -> None: AddShareDialog(self).present(self) def show_about_dialog(self) -> None: - dialog = Gtk.AboutDialog() - dialog.set_transient_for(self) - dialog.set_modal(True) - dialog.set_program_name(APP_NAME) - dialog.set_logo_icon_name(APP_ICON_NAME) - dialog.set_comments("Create and manage on-demand SMB mounts.") - dialog.set_authors(APP_DEVELOPERS) - dialog.add_credit_section("Developed by", APP_DEVELOPERS) - dialog.set_website(APP_WEBSITE) - dialog.set_website_label("Project homepage") - dialog.set_license_type(Gtk.License.GPL_3_0_ONLY) - dialog.present() + about = Adw.AboutDialog( + application_name=APP_NAME, + application_icon=APP_ICON_NAME, + developer_name=APP_DEVELOPERS[0] if APP_DEVELOPERS else "", + website=APP_WEBSITE, + issue_url=f"{APP_WEBSITE}/issues", + license_type=Gtk.License.GPL_3_0_ONLY, + comments="Create and manage on-demand SMB mounts.", + ) + about.set_developers(APP_DEVELOPERS) + about.present(self) def open_mount_folder(self, record: ManagedMount) -> None: if not record.mount_point.exists(): From da0dd32ed2d0c4fc17126e48571cb985ecd50e93 Mon Sep 17 00:00:00 2001 From: meowtypes Date: Thu, 28 May 2026 03:59:11 -0700 Subject: [PATCH 16/41] build: include mount_manager_ui in packaging and document libadwaita requirement --- README.md | 3 +++ packaging/build-appimage.sh | 1 + 2 files changed, 4 insertions(+) diff --git a/README.md b/README.md index 7ea9246..ee68424 100644 --- a/README.md +++ b/README.md @@ -24,6 +24,8 @@ Credentials and app metadata are stored under: systemd 258 or newer with `systemd-creds` available. The app refuses to start on older systems. +libadwaita 1.5 or newer. The app refuses to start on older versions. + Credentials are always stored encrypted via `systemd-creds` and decrypted by systemd at unit start, exposed to `mount.cifs` through `LoadCredentialEncrypted=`. The plaintext password never touches disk, and the encrypted blob is bound to @@ -73,6 +75,7 @@ Install the app files into the overlay: ```bash sudo install -D -m 0755 mount_manager.py /usr/bin/mount-manager +sudo install -D -m 0644 mount_manager_ui.py /usr/bin/mount_manager_ui.py sudo install -D -m 0644 data/applications/io.github.xarishark.mount-manager.desktop /usr/share/applications/io.github.xarishark.mount-manager.desktop sudo install -D -m 0644 data/icons/hicolor/scalable/apps/io.github.xarishark.mount-manager.svg /usr/share/icons/hicolor/scalable/apps/io.github.xarishark.mount-manager.svg sudo install -D -m 0644 data/metainfo/io.github.xarishark.mount-manager.metainfo.xml /usr/share/metainfo/io.github.xarishark.mount-manager.metainfo.xml diff --git a/packaging/build-appimage.sh b/packaging/build-appimage.sh index 4132ed8..b495770 100755 --- a/packaging/build-appimage.sh +++ b/packaging/build-appimage.sh @@ -88,6 +88,7 @@ mkdir -p "$appdir/usr/share/metainfo" mkdir -p "$dist_dir" install -D -m 0755 "$repo_root/mount_manager.py" "$appdir/usr/bin/mount-manager" +install -D -m 0644 "$repo_root/mount_manager_ui.py" "$appdir/usr/bin/mount_manager_ui.py" if ! command -v git >/dev/null 2>&1; then echo "git is required to apply the AppImage helper workaround." >&2 exit 1 From 7c1d568bf7e2929eaabbf8aae7054372a86dc3e7 Mon Sep 17 00:00:00 2001 From: meowtypes Date: Thu, 28 May 2026 04:05:25 -0700 Subject: [PATCH 17/41] chore: remove dead code after libadwaita migration --- mount_manager.py | 36 ------------------------------------ mount_manager_ui.py | 3 +-- 2 files changed, 1 insertion(+), 38 deletions(-) diff --git a/mount_manager.py b/mount_manager.py index 04d362d..62dca00 100644 --- a/mount_manager.py +++ b/mount_manager.py @@ -32,7 +32,6 @@ APP_CREATOR = "Zacharias Xenakis (Xarishark)" APP_DEVELOPERS = [APP_CREATOR] APP_WEBSITE = "https://github.com/Xarishark/mount-manager" -COLOR_SCHEME_ENV = "MOUNT_MANAGER_COLOR_SCHEME" APP_ICON_NAME = APP_ID MANAGED_ROOT = Path("/etc/mount-manager") @@ -922,41 +921,6 @@ def load_displayed_mounts() -> list[DisplayedMount]: return displayed -def detect_color_scheme(env: dict[str, str] | None = None) -> str: - if env is None: - env = os.environ - - explicit = env.get(COLOR_SCHEME_ENV, "").strip().lower() - if explicit in {"dark", "light"}: - return explicit - - gtk_theme = env.get("GTK_THEME", "").lower() - if "dark" in gtk_theme: - return "dark" - if "light" in gtk_theme: - return "light" - - try: - result = subprocess.run( - ["gsettings", "get", "org.gnome.desktop.interface", "color-scheme"], - check=False, - text=True, - stdout=subprocess.PIPE, - stderr=subprocess.PIPE, - timeout=2, - ) - except (FileNotFoundError, subprocess.SubprocessError): - return "light" - - if result.returncode != 0: - return "light" - - value = result.stdout.strip().strip("'\"").lower() - if value == "prefer-dark": - return "dark" - return "light" - - def run_privileged_helper(action: str, payload: dict[str, Any]) -> dict[str, Any]: pkexec = shutil.which("pkexec") if pkexec is None: diff --git a/mount_manager_ui.py b/mount_manager_ui.py index b3ff147..07c6b31 100644 --- a/mount_manager_ui.py +++ b/mount_manager_ui.py @@ -15,8 +15,7 @@ gi.require_version("Adw", "1") gi.require_version("Gdk", "4.0") gi.require_version("Gtk", "4.0") -gi.require_version("Pango", "1.0") -from gi.repository import Adw, Gdk, Gio, GLib, Gtk, Pango # noqa: E402 +from gi.repository import Adw, Gdk, Gio, GLib, Gtk # noqa: E402 def GLib_markup_escape(text: str) -> str: From c01dfff79562f34f152321de73fa3ec203979f94 Mon Sep 17 00:00:00 2001 From: meowtypes Date: Thu, 28 May 2026 04:14:56 -0700 Subject: [PATCH 18/41] docs: add agent guidance for architecture, UI conventions, and packaging --- AGENTS.md | 82 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 82 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..5250cd8 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,82 @@ +# AGENTS.md + +## Architecture + +The application is split across two files: + +- `mount_manager.py` — entry point, constants, dataclasses (`SharePath`, `ManagedMount`, + `DisplayedMount`), exceptions, privileged helper-mode logic (`run_helper_mode`), polkit + invocations (`request_helper_*`), and pure helpers (`check_smb_host_reachable`, + `load_displayed_mounts`, `validate_credentials`, `_libadwaita_supports`). + This module **must remain importable without a display and without libadwaita**: it is + re-executed as root via `pkexec /usr/bin/mount-manager --helper …` and that path must + not pull in GTK/Adw. Keep all GUI imports lazy (inside `run_gui()`). +- `mount_manager_ui.py` — all GTK4 / libadwaita UI. Defines a thin module-level + `run_gui()` that contains the `MainWindow`, `AddShareDialog`, and + `MountManagerApplication` classes nested inside it. Imports the data + helpers it needs + from `mount_manager`. + +`mount_manager.run_gui()` is a one-line shim that imports `mount_manager_ui` lazily so the +`--helper` path never loads GUI code. + +## UI conventions (libadwaita ≥ 1.5) + +- Minimum libadwaita version is enforced by `mount_manager._libadwaita_supports` and + `ensure_libadwaita_supported()` in `mount_manager_ui`. Bumping `MIN_LIBADWAITA_VERSION` + in `mount_manager.py` is the single source of truth. +- Color scheme is delegated to `Adw.StyleManager` (`ColorScheme.DEFAULT`). Do not + re-introduce custom CSS for theming or a custom color-scheme detector. +- The mount list uses `Adw.PreferencesPage` → `Adw.PreferencesGroup` → `Adw.ActionRow` + per mount with the **hybrid row pattern**: switch + one inline primary suffix + (open-folder or Upgrade) + kebab `MenuButton` containing destructive actions. + Unmanaged shares show a "Not managed" label and no controls. +- To enumerate or clear rows in an `Adw.PreferencesGroup`, use + `group.get_row(index)` — not `get_first_child()`, which returns the group's internal + structure widgets, not the `ActionRow` children. +- Status / error messages are surfaced as `Adw.Toast` via `MainWindow.show_toast()`. + Do not add new `Gtk.Window` / `Adw.Window` message dialogs. +- Confirmation prompts use `Adw.AlertDialog`; destructive responses get + `Adw.ResponseAppearance.DESTRUCTIVE`. +- The Add Share flow is a single-page progressive-reveal `Adw.Dialog` with a 300ms + debounced host check (`GLib.timeout_add` + `GLib.source_remove`). Any pending timer + **must** be cancelled on the dialog's `"closed"` signal to avoid firing callbacks on + destroyed widgets. +- Always escape user-controlled strings (mount paths, statuses) with + `GLib.markup_escape_text` before passing them to widgets that render Pango markup. +- About box uses `Adw.AboutDialog`. + +## Tests + +- Stock `unittest` only — no pytest, no new dependencies. +- Run: `python3 -m unittest discover -s tests -v` +- Unit-test pure-Python helpers (e.g. `_libadwaita_supports`, `mount_status_line`). + Widget construction is verified manually — do not add headless GTK widget-tree + assertions to the test suite. + +## Packaging + +- `packaging/build-appimage.sh` installs both `mount_manager.py` (as `mount-manager`) and + `mount_manager_ui.py` (verbatim filename) into `$appdir/usr/bin/`. Python's + `sys.path[0]` covers the script directory, so the bare `import mount_manager_ui` in the + GUI shim resolves without `sys.path` manipulation. +- `packaging/appimage-helper.patch` rewrites the helper invocation so the AppImage + re-execs itself under `pkexec`. Do not change the helper CLI surface + (`--helper {create|delete|upgrade|set-enabled}`) without updating this patch. +- If you add a new top-level Python module that the GUI imports, you must add a matching + `install` line in `packaging/build-appimage.sh` AND in the README's manual-install + section. + +## Reference docs + +- Design spec: `docs/superpowers/specs/2026-05-28-libadwaita-migration-design.md` +- Implementation plan (executed, kept for context): `docs/superpowers/plans/2026-05-28-libadwaita-migration.md` + +## Working rules +- Prefer native tools (view/edit/create/grep/glob) over shell for file reading, editing, and + searching. Use shell only when there is no native equivalent (running tests, builds, git, gh, + packaging). +- Ad-hoc `python3 -c '...'` snippets for verification are fine. Do not add new throwaway scripts + to the repo; if a check is worth keeping, make it a unittest under `tests/`. +- Ask before any destructive or irreversible operation: force-push, history rewrites, deleting + branches that exist on the remote, mass file deletion, or modifying files outside the repo. +- Do not add `Co-authored-by:` trailers to commit messages. From 988f7db2951c2fd665c147b20af07dc9afaf6d2b Mon Sep 17 00:00:00 2001 From: meowtypes Date: Thu, 28 May 2026 04:30:25 -0700 Subject: [PATCH 19/41] fix(ui): run AddShareDialog host check off the main thread Previously check_smb_host_reachable ran on the GTK main loop, freezing the UI for up to 4 seconds (DNS + TCP connect timeout) when the host could not be reached. Now the call runs in a daemon thread, the result is marshalled back via GLib.idle_add, and cancellation is driven by a Gio.Cancellable so that: - typing more characters cancels the in-flight check and starts a fresh one (no stale result clobbers the UI), - closing the dialog cancels the check so its callback never touches destroyed widgets. --- mount_manager_ui.py | 52 +++++++++++++++++++++++++++++++++++++++------ 1 file changed, 46 insertions(+), 6 deletions(-) diff --git a/mount_manager_ui.py b/mount_manager_ui.py index 07c6b31..9b8149d 100644 --- a/mount_manager_ui.py +++ b/mount_manager_ui.py @@ -8,6 +8,7 @@ from __future__ import annotations import sys +import threading from typing import Any import gi @@ -98,6 +99,7 @@ def __init__(self, main_window: "MainWindow") -> None: self.main_window = main_window self.share_path: SharePath | None = None self._debounce_id: int = 0 + self._cancellable: Gio.Cancellable | None = None self.cancel_button = Gtk.Button(label="Cancel") self.cancel_button.connect("clicked", lambda _b: self.close()) @@ -167,6 +169,9 @@ def __init__(self, main_window: "MainWindow") -> None: self.connect("closed", self._cleanup) def _cleanup(self, *_args) -> None: + if self._cancellable is not None: + self._cancellable.cancel() + self._cancellable = None if self._debounce_id: GLib.source_remove(self._debounce_id) self._debounce_id = 0 @@ -198,6 +203,9 @@ def _on_path_changed(self) -> None: self._update_add_sensitive() self._hide_banner() self._set_host_status(ok=None, message="") + if self._cancellable is not None: + self._cancellable.cancel() + self._cancellable = None if self._debounce_id: GLib.source_remove(self._debounce_id) self._debounce_id = 0 @@ -208,22 +216,54 @@ def _on_path_changed(self) -> None: def _run_host_check(self) -> bool: self._debounce_id = 0 + text = self.path_row.get_text() + cancellable = Gio.Cancellable() + self._cancellable = cancellable self.host_spinner.set_visible(True) self.host_spinner.start() + thread = threading.Thread( + target=self._host_check_worker, + args=(cancellable, text), + daemon=True, + ) + thread.start() + return False # don't repeat the timeout + + def _host_check_worker( + self, cancellable: Gio.Cancellable, text: str + ) -> None: try: - share_path = check_smb_host_reachable(self.path_row.get_text()) + share_path = check_smb_host_reachable(text) except MountManagerError as exc: - self._set_host_status(ok=False, message=str(exc)) - return False + result: tuple[SharePath | None, BaseException | None] = (None, exc) except Exception as exc: - self._set_host_status(ok=False, message=f"Unexpected error: {exc}") + result = (None, exc) + else: + result = (share_path, None) + if cancellable.is_cancelled(): + return + GLib.idle_add(self._on_host_check_done, cancellable, result[0], result[1]) + + def _on_host_check_done( + self, + cancellable: Gio.Cancellable, + share_path: SharePath | None, + exc: BaseException | None, + ) -> bool: + if cancellable.is_cancelled() or cancellable is not self._cancellable: + return False # stale or cancelled; ignore + self._cancellable = None + if exc is not None: + if isinstance(exc, MountManagerError): + self._set_host_status(ok=False, message=str(exc)) + else: + self._set_host_status(ok=False, message=f"Unexpected error: {exc}") return False - self.share_path = share_path self._set_host_status(ok=True, message="Host is reachable") self.credentials_group.set_sensitive(True) self._update_add_sensitive() - return False # don't repeat the timeout + return False def _update_add_sensitive(self) -> None: ready = ( From 8edcbfc307bd7486b578bee3eb618049eef987e0 Mon Sep 17 00:00:00 2001 From: meowtypes Date: Thu, 28 May 2026 04:48:49 -0700 Subject: [PATCH 20/41] fix(ui): correct post-create toast wording The Add Share success toast claimed the share would mount when accessed, but request_helper_create mounts the share immediately and the refreshed row already reflects the mounted state. Drop the speculative claim and just confirm the action. --- mount_manager_ui.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mount_manager_ui.py b/mount_manager_ui.py index 9b8149d..60b4dfe 100644 --- a/mount_manager_ui.py +++ b/mount_manager_ui.py @@ -291,7 +291,7 @@ def _on_add_clicked(self) -> None: self.close() self.main_window.refresh() - self.main_window.show_toast(f"{share} will mount when accessed.") + self.main_window.show_toast(f"{share} added.") class MainWindow(Adw.ApplicationWindow): def __init__(self, app: Adw.Application) -> None: From 4e2882b5f898d3f12536c5799c11ee3fee1e833c Mon Sep 17 00:00:00 2001 From: meowtypes Date: Thu, 28 May 2026 04:50:00 -0700 Subject: [PATCH 21/41] fix(ui): correct post-upgrade toast wording Drop the speculative "will mount when accessed" suffix from the upgrade toast for the same reason as the create toast: the refreshed row already reflects the actual mount state, so the toast should only confirm the action. --- mount_manager_ui.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mount_manager_ui.py b/mount_manager_ui.py index 60b4dfe..2b42ecd 100644 --- a/mount_manager_ui.py +++ b/mount_manager_ui.py @@ -485,7 +485,7 @@ def upgrade_mount(self, record: ManagedMount) -> None: self.show_toast(f"Upgrade failed: {exc}") return self.refresh() - self.show_toast(f"{record.source} upgraded; will mount when accessed.") + self.show_toast(f"{record.source} upgraded.") def toggle_mount(self, record: ManagedMount, switch: Gtk.Switch) -> None: enabled = switch.get_active() From aad8e4b24a205aaa6f4478df9d3cd343ab673fb4 Mon Sep 17 00:00:00 2001 From: meowtypes Date: Thu, 28 May 2026 13:34:00 -0700 Subject: [PATCH 22/41] fix(ui): align UI copy with GNOME HIG (toasts, tooltips, labels) --- mount_manager_ui.py | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/mount_manager_ui.py b/mount_manager_ui.py index 2b42ecd..881962f 100644 --- a/mount_manager_ui.py +++ b/mount_manager_ui.py @@ -291,7 +291,7 @@ def _on_add_clicked(self) -> None: self.close() self.main_window.refresh() - self.main_window.show_toast(f"{share} added.") + self.main_window.show_toast(f"{share} added") class MainWindow(Adw.ApplicationWindow): def __init__(self, app: Adw.Application) -> None: @@ -308,14 +308,14 @@ def __init__(self, app: Adw.Application) -> None: menu_button = Gtk.MenuButton(icon_name="open-menu-symbolic") menu_button.set_menu_model(menu) - menu_button.set_tooltip_text("Main menu") + menu_button.set_tooltip_text("Primary menu") refresh_button = Gtk.Button.new_from_icon_name("view-refresh-symbolic") refresh_button.set_tooltip_text("Refresh") refresh_button.connect("clicked", lambda _b: self.refresh()) add_button = Gtk.Button(label="Add Share") - add_button.set_tooltip_text("Add share") + add_button.set_tooltip_text("Mount a new SMB share") add_button.add_css_class("suggested-action") add_button.connect("clicked", lambda _b: self.show_add_dialog()) @@ -333,7 +333,7 @@ def __init__(self, app: Adw.Application) -> None: self.empty_page = Adw.StatusPage() self.empty_page.set_icon_name("folder-remote-symbolic") self.empty_page.set_title("No SMB shares") - self.empty_page.set_description("Click Add Share to mount one.") + self.empty_page.set_description('Click "Add Share" to mount one') self.empty_page.set_vexpand(True) empty_action = Gtk.Button(label="Add Share") @@ -347,7 +347,6 @@ def __init__(self, app: Adw.Application) -> None: self.preferences_page.set_vexpand(True) self.mount_group = Adw.PreferencesGroup() - self.mount_group.set_title("SMB Shares") self.preferences_page.add(self.mount_group) self.content_box.append(self.preferences_page) @@ -485,7 +484,7 @@ def upgrade_mount(self, record: ManagedMount) -> None: self.show_toast(f"Upgrade failed: {exc}") return self.refresh() - self.show_toast(f"{record.source} upgraded.") + self.show_toast(f"{record.source} upgraded") def toggle_mount(self, record: ManagedMount, switch: Gtk.Switch) -> None: enabled = switch.get_active() @@ -508,7 +507,7 @@ def confirm_delete(self, record: ManagedMount) -> None: ), ) alert.add_response("cancel", "Cancel") - alert.add_response("delete", "Delete") + alert.add_response("delete", "Delete Share") alert.set_response_appearance( "delete", Adw.ResponseAppearance.DESTRUCTIVE ) @@ -531,7 +530,7 @@ def _on_delete_response( self.show_toast(f"Delete failed: {exc}") return self.refresh() - self.show_toast(f"{record.source} removed.") + self.show_toast(f"{record.source} removed") class MountManagerApplication(Adw.Application): def __init__(self) -> None: From 1dc470f621cbc6fa45830d6dabba13a59ce8a87d Mon Sep 17 00:00:00 2001 From: meowtypes Date: Thu, 28 May 2026 13:37:21 -0700 Subject: [PATCH 23/41] refactor(ui): use modern symbolic icon names --- mount_manager_ui.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/mount_manager_ui.py b/mount_manager_ui.py index 881962f..5470d20 100644 --- a/mount_manager_ui.py +++ b/mount_manager_ui.py @@ -191,9 +191,9 @@ def _set_host_status(self, *, ok: bool | None, message: str) -> None: self.path_row.set_title("Share path") return if ok: - self.host_status_icon.set_from_icon_name("emblem-ok-symbolic") + self.host_status_icon.set_from_icon_name("checkmark-symbolic") else: - self.host_status_icon.set_from_icon_name("dialog-error-symbolic") + self.host_status_icon.set_from_icon_name("error-symbolic") self.host_status_icon.set_visible(True) self.host_status_icon.set_tooltip_text(message) @@ -331,7 +331,7 @@ def __init__(self, app: Adw.Application) -> None: self.toast_overlay.set_child(self.content_box) self.empty_page = Adw.StatusPage() - self.empty_page.set_icon_name("folder-remote-symbolic") + self.empty_page.set_icon_name("network-server-symbolic") self.empty_page.set_title("No SMB shares") self.empty_page.set_description('Click "Add Share" to mount one') self.empty_page.set_vexpand(True) From 6cf738500b4cabfd0e1b8e64622cf0a3c6cc9cf9 Mon Sep 17 00:00:00 2001 From: meowtypes Date: Thu, 28 May 2026 13:39:04 -0700 Subject: [PATCH 24/41] fix(ui): improve AddShareDialog focus and keyboard submit --- mount_manager_ui.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/mount_manager_ui.py b/mount_manager_ui.py index 5470d20..51adc5b 100644 --- a/mount_manager_ui.py +++ b/mount_manager_ui.py @@ -110,8 +110,6 @@ def __init__(self, main_window: "MainWindow") -> None: self.add_button.connect("clicked", lambda _b: self._on_add_clicked()) header = Adw.HeaderBar() - header.set_show_start_title_buttons(False) - header.set_show_end_title_buttons(False) header.pack_start(self.cancel_button) header.pack_end(self.add_button) @@ -165,8 +163,10 @@ def __init__(self, main_window: "MainWindow") -> None: toolbar.add_top_bar(header) toolbar.set_content(body) self.set_child(toolbar) + self.set_default_widget(self.add_button) self.connect("closed", self._cleanup) + self.connect("map", lambda _d: self.path_row.grab_focus()) def _cleanup(self, *_args) -> None: if self._cancellable is not None: From 0abfaa4c636e382554211b5c4988265578595db3 Mon Sep 17 00:00:00 2001 From: meowtypes Date: Thu, 28 May 2026 13:40:39 -0700 Subject: [PATCH 25/41] refactor(ui): drop duplicate developer field in About dialog --- mount_manager_ui.py | 1 - 1 file changed, 1 deletion(-) diff --git a/mount_manager_ui.py b/mount_manager_ui.py index 51adc5b..5861854 100644 --- a/mount_manager_ui.py +++ b/mount_manager_ui.py @@ -456,7 +456,6 @@ def show_about_dialog(self) -> None: about = Adw.AboutDialog( application_name=APP_NAME, application_icon=APP_ICON_NAME, - developer_name=APP_DEVELOPERS[0] if APP_DEVELOPERS else "", website=APP_WEBSITE, issue_url=f"{APP_WEBSITE}/issues", license_type=Gtk.License.GPL_3_0_ONLY, From e116d3a5565ac1b34d6b1ef84d5f8690a277f2ad Mon Sep 17 00:00:00 2001 From: meowtypes Date: Thu, 28 May 2026 13:42:27 -0700 Subject: [PATCH 26/41] fix(ui): restyle header-bar Add Share button to follow HIG --- mount_manager_ui.py | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/mount_manager_ui.py b/mount_manager_ui.py index 5861854..a0567ed 100644 --- a/mount_manager_ui.py +++ b/mount_manager_ui.py @@ -314,9 +314,13 @@ def __init__(self, app: Adw.Application) -> None: refresh_button.set_tooltip_text("Refresh") refresh_button.connect("clicked", lambda _b: self.refresh()) - add_button = Gtk.Button(label="Add Share") + add_button_content = Adw.ButtonContent( + icon_name="list-add-symbolic", + label="Add Share", + ) + add_button = Gtk.Button() + add_button.set_child(add_button_content) add_button.set_tooltip_text("Mount a new SMB share") - add_button.add_css_class("suggested-action") add_button.connect("clicked", lambda _b: self.show_add_dialog()) header = Adw.HeaderBar() From 9097b9d679e59854e6806d32251a20c2f6ad3989 Mon Sep 17 00:00:00 2001 From: meowtypes Date: Thu, 28 May 2026 13:47:26 -0700 Subject: [PATCH 27/41] feat(ui): add keyboard shortcuts and shortcuts window --- mount_manager_ui.py | 81 +++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 74 insertions(+), 7 deletions(-) diff --git a/mount_manager_ui.py b/mount_manager_ui.py index a0567ed..b7456e9 100644 --- a/mount_manager_ui.py +++ b/mount_manager_ui.py @@ -91,6 +91,32 @@ def run_gui() -> int: return 1 apply_style_manager() + def build_shortcuts_window(parent: Gtk.Window) -> Gtk.ShortcutsWindow: + """Construct the keyboard shortcuts dialog for the app.""" + window = Gtk.ShortcutsWindow(transient_for=parent, modal=True) + + section = Gtk.ShortcutsSection(section_name="main", visible=True) + + general = Gtk.ShortcutsGroup(title="General") + general.append( + Gtk.ShortcutsShortcut(title="Add Share", accelerator="n") + ) + general.append(Gtk.ShortcutsShortcut(title="Refresh", accelerator="r")) + general.append(Gtk.ShortcutsShortcut(title="Primary Menu", accelerator="F10")) + general.append( + Gtk.ShortcutsShortcut( + title="Keyboard Shortcuts", accelerator="question" + ) + ) + general.append( + Gtk.ShortcutsShortcut(title="Close Window", accelerator="w") + ) + general.append(Gtk.ShortcutsShortcut(title="Quit", accelerator="q")) + section.append(general) + + window.add_section(section) + return window + class AddShareDialog(Adw.Dialog): def __init__(self, main_window: "MainWindow") -> None: super().__init__() @@ -303,16 +329,37 @@ def __init__(self, app: Adw.Application) -> None: about_action.connect("activate", lambda _a, _p: self.show_about_dialog()) self.add_action(about_action) + close_action = Gio.SimpleAction.new("close", None) + close_action.connect("activate", lambda _a, _p: self.close()) + self.add_action(close_action) + app.set_accels_for_action("win.close", ["w"]) + + add_share_action = Gio.SimpleAction.new("add-share", None) + add_share_action.connect("activate", lambda _a, _p: self.show_add_dialog()) + self.add_action(add_share_action) + app.set_accels_for_action("win.add-share", ["n"]) + + refresh_action = Gio.SimpleAction.new("refresh", None) + refresh_action.connect("activate", lambda _a, _p: self.refresh()) + self.add_action(refresh_action) + app.set_accels_for_action("win.refresh", ["r"]) + + show_menu_action = Gio.SimpleAction.new("show-menu", None) + show_menu_action.connect("activate", lambda _a, _p: self._open_primary_menu()) + self.add_action(show_menu_action) + app.set_accels_for_action("win.show-menu", ["F10"]) + menu = Gio.Menu() + menu.append("Keyboard Shortcuts", "app.shortcuts") menu.append(f"About {APP_NAME}", "win.about") - menu_button = Gtk.MenuButton(icon_name="open-menu-symbolic") - menu_button.set_menu_model(menu) - menu_button.set_tooltip_text("Primary menu") + self.menu_button = Gtk.MenuButton(icon_name="open-menu-symbolic") + self.menu_button.set_menu_model(menu) + self.menu_button.set_tooltip_text("Primary menu") refresh_button = Gtk.Button.new_from_icon_name("view-refresh-symbolic") refresh_button.set_tooltip_text("Refresh") - refresh_button.connect("clicked", lambda _b: self.refresh()) + refresh_button.set_action_name("win.refresh") add_button_content = Adw.ButtonContent( icon_name="list-add-symbolic", @@ -321,11 +368,11 @@ def __init__(self, app: Adw.Application) -> None: add_button = Gtk.Button() add_button.set_child(add_button_content) add_button.set_tooltip_text("Mount a new SMB share") - add_button.connect("clicked", lambda _b: self.show_add_dialog()) + add_button.set_action_name("win.add-share") header = Adw.HeaderBar() header.pack_start(add_button) - header.pack_end(menu_button) + header.pack_end(self.menu_button) header.pack_end(refresh_button) self.toast_overlay = Adw.ToastOverlay() @@ -344,7 +391,7 @@ def __init__(self, app: Adw.Application) -> None: empty_action.set_halign(Gtk.Align.CENTER) empty_action.add_css_class("suggested-action") empty_action.add_css_class("pill") - empty_action.connect("clicked", lambda _b: self.show_add_dialog()) + empty_action.set_action_name("win.add-share") self.empty_page.set_child(empty_action) self.preferences_page = Adw.PreferencesPage() @@ -363,6 +410,9 @@ def __init__(self, app: Adw.Application) -> None: self.refresh() + def _open_primary_menu(self) -> None: + self.menu_button.popup() + def show_toast(self, message: str) -> None: self.toast_overlay.add_toast(Adw.Toast(title=message)) @@ -539,6 +589,23 @@ class MountManagerApplication(Adw.Application): def __init__(self) -> None: super().__init__(application_id=APP_ID, flags=Gio.ApplicationFlags.DEFAULT_FLAGS) + quit_action = Gio.SimpleAction.new("quit", None) + quit_action.connect("activate", lambda _a, _p: self.quit()) + self.add_action(quit_action) + self.set_accels_for_action("app.quit", ["q"]) + + shortcuts_action = Gio.SimpleAction.new("shortcuts", None) + shortcuts_action.connect("activate", lambda _a, _p: self._show_shortcuts()) + self.add_action(shortcuts_action) + self.set_accels_for_action("app.shortcuts", ["question"]) + + def _show_shortcuts(self) -> None: + window = self.props.active_window + if window is None: + return + shortcuts_window = build_shortcuts_window(window) + shortcuts_window.present() + def do_activate(self) -> None: window = self.props.active_window if window is None: From 3106ecb5c7c5894ba77c37c5c638a2a9da1c43e7 Mon Sep 17 00:00:00 2001 From: meowtypes Date: Thu, 28 May 2026 14:19:21 -0700 Subject: [PATCH 28/41] feat: raise minimum libadwaita to 1.8 --- README.md | 2 +- mount_manager.py | 4 ++-- tests/test_libadwaita_support.py | 6 +++--- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index ee68424..22fdd2e 100644 --- a/README.md +++ b/README.md @@ -24,7 +24,7 @@ Credentials and app metadata are stored under: systemd 258 or newer with `systemd-creds` available. The app refuses to start on older systems. -libadwaita 1.5 or newer. The app refuses to start on older versions. +libadwaita 1.8 or newer. The app refuses to start on older versions. Credentials are always stored encrypted via `systemd-creds` and decrypted by systemd at unit start, exposed to `mount.cifs` through `LoadCredentialEncrypted=`. diff --git a/mount_manager.py b/mount_manager.py index 62dca00..da4b761 100644 --- a/mount_manager.py +++ b/mount_manager.py @@ -49,8 +49,8 @@ # Mount-unit credentials (LoadCredentialEncrypted=) require this systemd version. MIN_SYSTEMD_VERSION = 258 -# Adw.Dialog and Adw.AlertDialog require libadwaita 1.5 or newer. -MIN_LIBADWAITA_VERSION: tuple[int, int] = (1, 5) +# Adw.ShortcutsDialog and Adw.Spinner require libadwaita 1.8 or newer. +MIN_LIBADWAITA_VERSION: tuple[int, int] = (1, 8) def _libadwaita_supports(major: int, minor: int) -> bool: diff --git a/tests/test_libadwaita_support.py b/tests/test_libadwaita_support.py index db2cc40..b18608e 100644 --- a/tests/test_libadwaita_support.py +++ b/tests/test_libadwaita_support.py @@ -7,16 +7,16 @@ class LibadwaitaSupportsTest(unittest.TestCase): def test_minimum_supported_version(self) -> None: - self.assertTrue(_libadwaita_supports(1, 5)) + self.assertTrue(_libadwaita_supports(1, 8)) def test_newer_minor_supported(self) -> None: - self.assertTrue(_libadwaita_supports(1, 7)) + self.assertTrue(_libadwaita_supports(1, 9)) def test_newer_major_supported(self) -> None: self.assertTrue(_libadwaita_supports(2, 0)) def test_older_minor_unsupported(self) -> None: - self.assertFalse(_libadwaita_supports(1, 4)) + self.assertFalse(_libadwaita_supports(1, 7)) def test_older_major_unsupported(self) -> None: self.assertFalse(_libadwaita_supports(0, 99)) From da80bf564fad87595228e82aba8f17a7035bafc3 Mon Sep 17 00:00:00 2001 From: meowtypes Date: Thu, 28 May 2026 14:22:51 -0700 Subject: [PATCH 29/41] refactor(ui): use Adw.Spinner in Add Share dialog --- mount_manager_ui.py | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/mount_manager_ui.py b/mount_manager_ui.py index b7456e9..468bb3b 100644 --- a/mount_manager_ui.py +++ b/mount_manager_ui.py @@ -156,7 +156,7 @@ def __init__(self, main_window: "MainWindow") -> None: self.path_row.connect("changed", lambda _r: self._on_path_changed()) share_group.add(self.path_row) - self.host_spinner = Gtk.Spinner() + self.host_spinner = Adw.Spinner() self.host_spinner.set_valign(Gtk.Align.CENTER) self.host_spinner.set_visible(False) self.path_row.add_suffix(self.host_spinner) @@ -211,7 +211,6 @@ def _hide_banner(self) -> None: def _set_host_status(self, *, ok: bool | None, message: str) -> None: self.host_spinner.set_visible(False) - self.host_spinner.stop() if ok is None: self.host_status_icon.set_visible(False) self.path_row.set_title("Share path") @@ -246,7 +245,6 @@ def _run_host_check(self) -> bool: cancellable = Gio.Cancellable() self._cancellable = cancellable self.host_spinner.set_visible(True) - self.host_spinner.start() thread = threading.Thread( target=self._host_check_worker, args=(cancellable, text), From 2a5a17c54a1b6cd75ceb11a19f2def6694a625f5 Mon Sep 17 00:00:00 2001 From: meowtypes Date: Thu, 28 May 2026 14:26:29 -0700 Subject: [PATCH 30/41] refactor(ui): use Adw.ShortcutsDialog for keyboard shortcuts --- mount_manager_ui.py | 39 ++++++++++++++++----------------------- 1 file changed, 16 insertions(+), 23 deletions(-) diff --git a/mount_manager_ui.py b/mount_manager_ui.py index 468bb3b..6eb9795 100644 --- a/mount_manager_ui.py +++ b/mount_manager_ui.py @@ -91,31 +91,24 @@ def run_gui() -> int: return 1 apply_style_manager() - def build_shortcuts_window(parent: Gtk.Window) -> Gtk.ShortcutsWindow: + def build_shortcuts_dialog() -> Adw.ShortcutsDialog: """Construct the keyboard shortcuts dialog for the app.""" - window = Gtk.ShortcutsWindow(transient_for=parent, modal=True) - - section = Gtk.ShortcutsSection(section_name="main", visible=True) - - general = Gtk.ShortcutsGroup(title="General") - general.append( - Gtk.ShortcutsShortcut(title="Add Share", accelerator="n") - ) - general.append(Gtk.ShortcutsShortcut(title="Refresh", accelerator="r")) - general.append(Gtk.ShortcutsShortcut(title="Primary Menu", accelerator="F10")) - general.append( - Gtk.ShortcutsShortcut( - title="Keyboard Shortcuts", accelerator="question" + dialog = Adw.ShortcutsDialog() + + general = Adw.ShortcutsSection(title="General") + general.add(Adw.ShortcutsItem(title="Add Share", action_name="win.add-share")) + general.add(Adw.ShortcutsItem(title="Refresh", action_name="win.refresh")) + general.add(Adw.ShortcutsItem(title="Primary Menu", action_name="win.show-menu")) + general.add( + Adw.ShortcutsItem( + title="Keyboard Shortcuts", action_name="app.shortcuts" ) ) - general.append( - Gtk.ShortcutsShortcut(title="Close Window", accelerator="w") - ) - general.append(Gtk.ShortcutsShortcut(title="Quit", accelerator="q")) - section.append(general) + general.add(Adw.ShortcutsItem(title="Close Window", action_name="win.close")) + general.add(Adw.ShortcutsItem(title="Quit", action_name="app.quit")) - window.add_section(section) - return window + dialog.add(general) + return dialog class AddShareDialog(Adw.Dialog): def __init__(self, main_window: "MainWindow") -> None: @@ -601,8 +594,8 @@ def _show_shortcuts(self) -> None: window = self.props.active_window if window is None: return - shortcuts_window = build_shortcuts_window(window) - shortcuts_window.present() + dialog = build_shortcuts_dialog() + dialog.present(window) def do_activate(self) -> None: window = self.props.active_window From b2e1fb3b06bd2bd3fc7c704e63164d98c3591733 Mon Sep 17 00:00:00 2001 From: meowtypes Date: Thu, 28 May 2026 14:30:49 -0700 Subject: [PATCH 31/41] refactor(ui): open mount folders with Gtk.FileLauncher --- mount_manager_ui.py | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/mount_manager_ui.py b/mount_manager_ui.py index 6eb9795..f5c291c 100644 --- a/mount_manager_ui.py +++ b/mount_manager_ui.py @@ -45,7 +45,6 @@ def GLib_VariantType(spec: str) -> GLib.VariantType: request_helper_delete, request_helper_set_enabled, request_helper_upgrade, - run_command, validate_credentials, ) @@ -513,10 +512,18 @@ def open_mount_folder(self, record: ManagedMount) -> None: if not record.mount_point.exists(): self.show_toast(f"Mount folder does not exist: {record.mount_point}") return + launcher = Gtk.FileLauncher.new(Gio.File.new_for_path(str(record.mount_point))) + launcher.launch(self, None, self._on_open_folder_done) + + def _on_open_folder_done( + self, launcher: Gtk.FileLauncher, result: Gio.AsyncResult + ) -> None: try: - run_command(["xdg-open", str(record.mount_point)]) - except MountManagerError as exc: - self.show_toast(f"Could not open {record.mount_point}: {exc}") + launcher.launch_finish(result) + except GLib.Error as exc: + if exc.matches(Gio.io_error_quark(), Gio.IOErrorEnum.CANCELLED): + return + self.show_toast(f"Could not open folder: {exc.message}") def upgrade_mount(self, record: ManagedMount) -> None: try: From 1ab82faa2cf7bfd07fed1844637117e4bf25a8c0 Mon Sep 17 00:00:00 2001 From: meowtypes Date: Thu, 28 May 2026 14:34:10 -0700 Subject: [PATCH 32/41] feat(ui): render mount rows as separate cards --- mount_manager_ui.py | 1 + 1 file changed, 1 insertion(+) diff --git a/mount_manager_ui.py b/mount_manager_ui.py index f5c291c..1a39331 100644 --- a/mount_manager_ui.py +++ b/mount_manager_ui.py @@ -388,6 +388,7 @@ def __init__(self, app: Adw.Application) -> None: self.preferences_page.set_vexpand(True) self.mount_group = Adw.PreferencesGroup() + self.mount_group.set_separate_rows(True) self.preferences_page.add(self.mount_group) self.content_box.append(self.preferences_page) From ff0f05f087233bea4f24671d56eb9cbbd366a57f Mon Sep 17 00:00:00 2001 From: meowtypes Date: Thu, 28 May 2026 14:40:09 -0700 Subject: [PATCH 33/41] docs: add HIG audit and libadwaita 1.8 bump specs and plans --- .../superpowers/plans/2026-05-28-hig-fixes.md | 707 ++++++++++++++++++ .../plans/2026-05-28-libadwaita-1.8-bump.md | 476 ++++++++++++ .../specs/2026-05-28-hig-fixes-design.md | 224 ++++++ .../2026-05-28-libadwaita-1.8-bump-design.md | 284 +++++++ 4 files changed, 1691 insertions(+) create mode 100644 docs/superpowers/plans/2026-05-28-hig-fixes.md create mode 100644 docs/superpowers/plans/2026-05-28-libadwaita-1.8-bump.md create mode 100644 docs/superpowers/specs/2026-05-28-hig-fixes-design.md create mode 100644 docs/superpowers/specs/2026-05-28-libadwaita-1.8-bump-design.md diff --git a/docs/superpowers/plans/2026-05-28-hig-fixes.md b/docs/superpowers/plans/2026-05-28-hig-fixes.md new file mode 100644 index 0000000..4717c54 --- /dev/null +++ b/docs/superpowers/plans/2026-05-28-hig-fixes.md @@ -0,0 +1,707 @@ +# HIG Fixes Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Address the findings in `~/mount-manager-hig-audit.md` so the libadwaita UI matches GNOME HIG conventions for copy, button styling, keyboard interaction, and accessibility. + +**Architecture:** Mostly surgical edits to `mount_manager_ui.py`. The largest task adds application-level `Gio.SimpleAction`s plus a `Gtk.ShortcutsWindow` for the M1 keyboard-accessibility gap. No new modules, no new test dependencies. Per `AGENTS.md`, widget trees are verified manually; existing pure-helper unit tests remain the only automated coverage. + +**Tech Stack:** Python 3, PyGObject (`gi`), GTK 4, libadwaita ≥ 1.5, stock `unittest`. + +**Source of truth for findings:** `~/mount-manager-hig-audit.md` (file lives outside the repo by user preference, NOT committed). + +**Branch:** `feat/libadwaita-01` (continue committing here; do not branch off). + +--- + +## File Map + +- Modify: `mount_manager_ui.py` — every task touches this file. +- Modify: `mount_manager.py` — only Task 6 (register an app-level `Ctrl+Q` accelerator on the `Adw.Application`). +- No new files. + +--- + +## Task 1: Copy & Terminology Fixes + +Addresses audit findings **m1, m2, m3, m4, m6, m7** — pure string changes. + +**Files:** +- Modify: `mount_manager_ui.py` + +- [ ] **Step 1: Strip trailing periods from toast titles (audit m1)** + +In `mount_manager_ui.py`, change these five toast strings: + +```python +# in MainWindow.open_mount_folder +self.show_toast(f"Mount folder does not exist: {record.mount_point}") +# becomes +self.show_toast(f"Mount folder does not exist: {record.mount_point}") # already no period — verify +``` + +Apply the period removal to: + +```python +# MainWindow.upgrade_mount +self.show_toast(f"{record.source} upgraded.") +# → +self.show_toast(f"{record.source} upgraded") +``` + +```python +# MainWindow._on_delete_response +self.show_toast(f"{record.source} removed.") +# → +self.show_toast(f"{record.source} removed") +``` + +```python +# AddShareDialog._on_add_clicked +self.main_window.show_toast(f"{share} added.") +# → +self.main_window.show_toast(f"{share} added") +``` + +Also remove the trailing period from every `f"… failed: {exc}"` toast — these end with the exception's text, which often already has no period; the literal `"failed:"` portion is fine. Audit only every toast string in the file and ensure none ends with a literal period in the format string. Specifically check: + +```python +self.show_toast(f"Upgrade failed: {exc}") # no trailing period — leave as-is +self.show_toast(f"Toggle failed: {exc}") # no trailing period — leave as-is +self.show_toast(f"Delete failed: {exc}") # no trailing period — leave as-is +self.show_toast(f"Could not open {record.mount_point}: {exc}") # leave +``` + +Search command to verify nothing was missed: + +```bash +grep -nE 'show_toast\(.*\.\"\)' mount_manager_ui.py +``` + +Expected: no matches. + +- [ ] **Step 2: Replace italic markup in empty-state description (audit m2)** + +In `MainWindow.__init__`, find: + +```python +self.empty_page.set_description("Click Add Share to mount one.") +``` + +Replace with: + +```python +self.empty_page.set_description('Click "Add Share" to mount one') +``` + +(Plain text, no Pango italics, no trailing period.) + +- [ ] **Step 3: Rewrite the header-bar Add Share tooltip (audit m3)** + +In `MainWindow.__init__`, find: + +```python +add_button = Gtk.Button(label="Add Share") +add_button.set_tooltip_text("Add share") +``` + +Replace the tooltip line with: + +```python +add_button.set_tooltip_text("Mount a new SMB share") +``` + +- [ ] **Step 4: Rename primary menu tooltip (audit m4)** + +In `MainWindow.__init__`, find: + +```python +menu_button.set_tooltip_text("Main menu") +``` + +Replace with: + +```python +menu_button.set_tooltip_text("Primary menu") +``` + +- [ ] **Step 5: Make the Delete confirmation button label more specific (audit m6)** + +In `MainWindow.confirm_delete`, find: + +```python +alert.add_response("delete", "Delete") +``` + +Replace with: + +```python +alert.add_response("delete", "Delete Share") +``` + +- [ ] **Step 6: Rename or drop the redundant mount group title (audit m7)** + +In `MainWindow.__init__`, find: + +```python +self.mount_group = Adw.PreferencesGroup() +self.mount_group.set_title("SMB Shares") +``` + +Replace with: + +```python +self.mount_group = Adw.PreferencesGroup() +``` + +(Drop the title entirely. Single-group preferences pages in libadwaita are conventionally untitled when the window title already provides context.) + +- [ ] **Step 7: Run the existing test suite** + +```bash +cd /var/home/mihlo/Projects/mount-manager +python3 -m unittest discover -s tests -v +``` + +Expected: 9 tests pass (no regressions). + +- [ ] **Step 8: Smoke-run the UI manually** + +```bash +python3 mount_manager.py +``` + +Verify: window opens, toasts (trigger one by toggling a switch off→on with the daemon stopped, if convenient, or by deleting a mount) have no trailing periods. Hover the header buttons to see the new tooltips. Hover-quit. + +- [ ] **Step 9: Commit** + +```bash +git add mount_manager_ui.py +git commit -m "fix(ui): align UI copy with GNOME HIG (toasts, tooltips, labels)" +``` + +--- + +## Task 2: Modernize Icon Names + +Addresses audit findings **n1** and **n2**. + +**Files:** +- Modify: `mount_manager_ui.py` + +- [ ] **Step 1: Replace legacy host-status icons (audit n1)** + +In `AddShareDialog._set_host_status`, find: + +```python +if ok: + self.host_status_icon.set_from_icon_name("emblem-ok-symbolic") +else: + self.host_status_icon.set_from_icon_name("dialog-error-symbolic") +``` + +Replace with: + +```python +if ok: + self.host_status_icon.set_from_icon_name("checkmark-symbolic") +else: + self.host_status_icon.set_from_icon_name("error-symbolic") +``` + +- [ ] **Step 2: Change the empty-state icon (audit n2)** + +In `MainWindow.__init__`, find: + +```python +self.empty_page.set_icon_name("folder-remote-symbolic") +``` + +Replace with: + +```python +self.empty_page.set_icon_name("network-server-symbolic") +``` + +- [ ] **Step 3: Smoke-run the UI manually** + +```bash +python3 mount_manager.py +``` + +Verify: + +1. Empty state (with no managed mounts) shows the network-server icon. +2. Open Add Share, type a reachable host like `//localhost/test` (or any host you know resolves) — the row should show a green check. +3. Type a definitely-unreachable host like `//unreachable.invalid/x` — the row should show a red error icon. + +If a fallback name lookup is needed for either icon, GTK's icon theme falls back gracefully and shows the missing-image glyph. If you see a missing-image glyph in either case, revert that specific name only and note it in the commit message. + +- [ ] **Step 4: Commit** + +```bash +git add mount_manager_ui.py +git commit -m "refactor(ui): use modern symbolic icon names" +``` + +--- + +## Task 3: AddShareDialog Ergonomics + +Addresses audit findings **m5** (default widget + initial focus) and **n3** (redundant header calls). + +**Files:** +- Modify: `mount_manager_ui.py` + +- [ ] **Step 1: Remove redundant header title-button calls (audit n3)** + +In `AddShareDialog.__init__`, find: + +```python +header = Adw.HeaderBar() +header.set_show_start_title_buttons(False) +header.set_show_end_title_buttons(False) +header.pack_start(self.cancel_button) +header.pack_end(self.add_button) +``` + +Replace with: + +```python +header = Adw.HeaderBar() +header.pack_start(self.cancel_button) +header.pack_end(self.add_button) +``` + +`AdwDialog` manages its own title-bar buttons, so these calls have no effect. + +- [ ] **Step 2: Set the Add button as the dialog's default widget (audit m5)** + +In `AddShareDialog.__init__`, immediately after `self.set_child(toolbar)` (and before the `self.connect("closed", self._cleanup)` line), add: + +```python +self.set_default_widget(self.add_button) +``` + +This makes the Add button respond to Enter from any focused entry once it becomes sensitive. The Add button is already gated by `_update_add_sensitive`, so Enter cannot submit prematurely. + +- [ ] **Step 3: Focus the share-path entry when the dialog opens (audit m5)** + +`Adw.Dialog` emits `map` when it becomes visible. In `AddShareDialog.__init__`, after the `self.connect("closed", self._cleanup)` line, add: + +```python +self.connect("map", lambda _d: self.path_row.grab_focus()) +``` + +- [ ] **Step 4: Smoke-run the UI manually** + +```bash +python3 mount_manager.py +``` + +Verify: + +1. Open Add Share — the share-path entry has focus immediately (you can type without clicking). +2. Type a valid host, fill in username and password. +3. Press Enter from the password field — the Add button is triggered (the dialog attempts the create instead of doing nothing). + +- [ ] **Step 5: Run the existing test suite** + +```bash +python3 -m unittest discover -s tests -v +``` + +Expected: 9 tests pass. + +- [ ] **Step 6: Commit** + +```bash +git add mount_manager_ui.py +git commit -m "fix(ui): improve AddShareDialog focus and keyboard submit" +``` + +--- + +## Task 4: About Dialog Cleanup + +Addresses audit finding **n4**. + +**Files:** +- Modify: `mount_manager_ui.py` + +- [ ] **Step 1: Remove the duplicate developer field** + +In `MainWindow.show_about_dialog`, find: + +```python +about = Adw.AboutDialog( + application_name=APP_NAME, + application_icon=APP_ICON_NAME, + developer_name=APP_DEVELOPERS[0] if APP_DEVELOPERS else "", + website=APP_WEBSITE, + issue_url=f"{APP_WEBSITE}/issues", + license_type=Gtk.License.GPL_3_0_ONLY, + comments="Create and manage on-demand SMB mounts.", +) +about.set_developers(APP_DEVELOPERS) +about.present(self) +``` + +Replace with: + +```python +about = Adw.AboutDialog( + application_name=APP_NAME, + application_icon=APP_ICON_NAME, + website=APP_WEBSITE, + issue_url=f"{APP_WEBSITE}/issues", + license_type=Gtk.License.GPL_3_0_ONLY, + comments="Create and manage on-demand SMB mounts.", +) +about.set_developers(APP_DEVELOPERS) +about.present(self) +``` + +`developer_name` is a single-line credit shown on the front page; `set_developers()` populates the Credits page list. Keep `set_developers` (it's the canonical list) and drop the `developer_name` constructor arg, which was redundant. + +- [ ] **Step 2: Smoke-run the UI manually** + +```bash +python3 mount_manager.py +``` + +Open the primary menu → "About SMB Mount Manager". Verify the dialog still opens, the Credits page lists the developer(s), and the front page does not show a duplicate name underneath the title. + +- [ ] **Step 3: Commit** + +```bash +git add mount_manager_ui.py +git commit -m "refactor(ui): drop duplicate developer field in About dialog" +``` + +--- + +## Task 5: Restyle the Header Bar "Add Share" Button + +Addresses audit findings **M2** (label-only suggested-action in primary header bar) and **M3** (two suggested-action buttons visible simultaneously). Fixing M2 fixes M3. + +**Files:** +- Modify: `mount_manager_ui.py` + +- [ ] **Step 1: Convert the header Add Share button to icon+label, drop suggested-action** + +In `MainWindow.__init__`, find: + +```python +add_button = Gtk.Button(label="Add Share") +add_button.set_tooltip_text("Mount a new SMB share") +add_button.add_css_class("suggested-action") +add_button.connect("clicked", lambda _b: self.show_add_dialog()) +``` + +Replace with: + +```python +add_button = Adw.ButtonContent( + icon_name="list-add-symbolic", + label="Add Share", +) +add_button_wrapper = Gtk.Button() +add_button_wrapper.set_child(add_button) +add_button_wrapper.set_tooltip_text("Mount a new SMB share") +add_button_wrapper.connect("clicked", lambda _b: self.show_add_dialog()) +``` + +Then update the `header.pack_start(add_button)` line below to: + +```python +header.pack_start(add_button_wrapper) +``` + +`Adw.ButtonContent` is the libadwaita helper that produces a consistent icon+label inside a `Gtk.Button`, and the header-bar style class will automatically remove the visible background per HIG (no `suggested-action` class needed — the pill button on `AdwStatusPage` is now the single suggested-action element in the empty state). + +- [ ] **Step 2: Smoke-run the UI manually** + +```bash +python3 mount_manager.py +``` + +Verify: + +1. Empty state: the header bar shows an Add Share icon+label button with no visible background or accent color; the pill in the centre is still blue (suggested). +2. Non-empty state: the header button still works and styled the same. +3. Resize the window narrow — the icon+label fits cleanly. +4. Hover the header button — tooltip still reads "Mount a new SMB share". + +- [ ] **Step 3: Run the existing test suite** + +```bash +python3 -m unittest discover -s tests -v +``` + +Expected: 9 tests pass. + +- [ ] **Step 4: Commit** + +```bash +git add mount_manager_ui.py +git commit -m "fix(ui): restyle header-bar Add Share button to follow HIG" +``` + +--- + +## Task 6: Keyboard Shortcuts + ShortcutsWindow + +Addresses audit finding **M1** — the largest single fix on the branch. + +**Approach:** + +- Add a `Gio.SimpleAction` for each shortcut on the `Adw.Application` (`app.quit`, `app.shortcuts`) and on the `MainWindow` (`win.close`, `win.add-share`, `win.refresh`, `win.show-menu`). +- Use `Gtk.Application.set_accels_for_action()` to bind shortcuts. +- Build a `Gtk.ShortcutsWindow` programmatically (no UI file — the rest of this codebase doesn't use them). +- Add a "Keyboard Shortcuts" entry to the primary menu above "About". +- Rewire existing handlers (refresh, add-share, about) through the new actions so accelerators and menu items both flow through the same code path. + +**Files:** +- Modify: `mount_manager_ui.py` +- Modify: `mount_manager.py` (only to install the `app.quit` accelerator on the `Adw.Application`) + +- [ ] **Step 1: Add the `Adw.Application` accelerators and `app.quit` / `app.shortcuts` actions** + +In `mount_manager_ui.py`, replace the entire `MountManagerApplication` class: + +```python +class MountManagerApplication(Adw.Application): + def __init__(self) -> None: + super().__init__(application_id=APP_ID, flags=Gio.ApplicationFlags.DEFAULT_FLAGS) + + def do_activate(self) -> None: + window = self.props.active_window + if window is None: + window = MainWindow(self) + window.present() +``` + +with: + +```python +class MountManagerApplication(Adw.Application): + def __init__(self) -> None: + super().__init__(application_id=APP_ID, flags=Gio.ApplicationFlags.DEFAULT_FLAGS) + + quit_action = Gio.SimpleAction.new("quit", None) + quit_action.connect("activate", lambda _a, _p: self.quit()) + self.add_action(quit_action) + self.set_accels_for_action("app.quit", ["q"]) + + shortcuts_action = Gio.SimpleAction.new("shortcuts", None) + shortcuts_action.connect("activate", lambda _a, _p: self._show_shortcuts()) + self.add_action(shortcuts_action) + self.set_accels_for_action("app.shortcuts", ["question"]) + + def _show_shortcuts(self) -> None: + window = self.props.active_window + if window is None: + return + shortcuts_window = build_shortcuts_window(window) + shortcuts_window.present() + + def do_activate(self) -> None: + window = self.props.active_window + if window is None: + window = MainWindow(self) + window.present() +``` + +- [ ] **Step 2: Add the `build_shortcuts_window` helper** + +In `mount_manager_ui.py`, *inside* `run_gui()` and **above** the `class AddShareDialog` definition, add: + +```python +def build_shortcuts_window(parent: Gtk.Window) -> Gtk.ShortcutsWindow: + """Construct the keyboard shortcuts dialog for the app.""" + window = Gtk.ShortcutsWindow(transient_for=parent, modal=True) + + section = Gtk.ShortcutsSection(section_name="main", visible=True) + + general = Gtk.ShortcutsGroup(title="General") + general.add_shortcut( + Gtk.ShortcutsShortcut(title="Add Share", accelerator="n") + ) + general.add_shortcut( + Gtk.ShortcutsShortcut(title="Refresh", accelerator="r") + ) + general.add_shortcut( + Gtk.ShortcutsShortcut(title="Primary Menu", accelerator="F10") + ) + general.add_shortcut( + Gtk.ShortcutsShortcut(title="Keyboard Shortcuts", accelerator="question") + ) + general.add_shortcut( + Gtk.ShortcutsShortcut(title="Close Window", accelerator="w") + ) + general.add_shortcut( + Gtk.ShortcutsShortcut(title="Quit", accelerator="q") + ) + section.add_group(general) + + window.add_section(section) + return window +``` + +Note: `Gtk.ShortcutsWindow` and its supporting classes (`ShortcutsSection`, `ShortcutsGroup`, `ShortcutsShortcut`) are part of GTK 4 and require no additional imports beyond `Gtk`, which is already imported. + +- [ ] **Step 3: Add window-level actions and accelerators in `MainWindow.__init__`** + +In `MainWindow.__init__`, find the existing about-action block: + +```python +about_action = Gio.SimpleAction.new("about", None) +about_action.connect("activate", lambda _a, _p: self.show_about_dialog()) +self.add_action(about_action) +``` + +Immediately after that block, add: + +```python +close_action = Gio.SimpleAction.new("close", None) +close_action.connect("activate", lambda _a, _p: self.close()) +self.add_action(close_action) +app.set_accels_for_action("win.close", ["w"]) + +add_share_action = Gio.SimpleAction.new("add-share", None) +add_share_action.connect("activate", lambda _a, _p: self.show_add_dialog()) +self.add_action(add_share_action) +app.set_accels_for_action("win.add-share", ["n"]) + +refresh_action = Gio.SimpleAction.new("refresh", None) +refresh_action.connect("activate", lambda _a, _p: self.refresh()) +self.add_action(refresh_action) +app.set_accels_for_action("win.refresh", ["r"]) + +show_menu_action = Gio.SimpleAction.new("show-menu", None) +show_menu_action.connect("activate", lambda _a, _p: self._open_primary_menu()) +self.add_action(show_menu_action) +app.set_accels_for_action("win.show-menu", ["F10"]) +``` + +- [ ] **Step 4: Hold a reference to the menu button so F10 can open it** + +In `MainWindow.__init__`, find: + +```python +menu_button = Gtk.MenuButton(icon_name="open-menu-symbolic") +menu_button.set_menu_model(menu) +menu_button.set_tooltip_text("Primary menu") +``` + +Replace with: + +```python +self.menu_button = Gtk.MenuButton(icon_name="open-menu-symbolic") +self.menu_button.set_menu_model(menu) +self.menu_button.set_tooltip_text("Primary menu") +``` + +And update the `header.pack_end(menu_button)` line further down to: + +```python +header.pack_end(self.menu_button) +``` + +Then add the helper method on `MainWindow` (anywhere convenient — next to `show_toast` is fine): + +```python +def _open_primary_menu(self) -> None: + self.menu_button.popup() +``` + +- [ ] **Step 5: Add a "Keyboard Shortcuts" entry to the primary menu** + +In `MainWindow.__init__`, find: + +```python +menu = Gio.Menu() +menu.append(f"About {APP_NAME}", "win.about") +``` + +Replace with: + +```python +menu = Gio.Menu() +menu.append("Keyboard Shortcuts", "app.shortcuts") +menu.append(f"About {APP_NAME}", "win.about") +``` + +The Keyboard Shortcuts entry will automatically display its accelerator (`Ctrl+?`) once `set_accels_for_action` has been called for `app.shortcuts`. + +- [ ] **Step 6: Smoke-run the UI manually** + +```bash +python3 mount_manager.py +``` + +Verify each accelerator: + +1. `Ctrl+N` — opens Add Share dialog. +2. `Ctrl+R` — refresh fires (rows reload; if you're watching `journalctl`, you'll see the systemd queries re-run). +3. `F10` — primary menu opens. Press `F10` again or `Esc` to dismiss. +4. `Ctrl+?` — Keyboard Shortcuts dialog opens, listing all six shortcuts. Press `Esc` to close. +5. `Ctrl+W` — closes the window. +6. Reopen the app. `Ctrl+Q` — quits the app entirely. +7. Open the primary menu — "Keyboard Shortcuts" appears above "About SMB Mount Manager", with its accelerator badge. + +- [ ] **Step 7: Run the existing test suite** + +```bash +python3 -m unittest discover -s tests -v +``` + +Expected: 9 tests pass (no regressions). + +- [ ] **Step 8: Commit** + +```bash +git add mount_manager_ui.py +git commit -m "feat(ui): add keyboard shortcuts and shortcuts window" +``` + +--- + +## Task 7: Final Verification + +- [ ] **Step 1: Run the full test suite one more time** + +```bash +cd /var/home/mihlo/Projects/mount-manager +python3 -m unittest discover -s tests -v +``` + +Expected: 9 tests pass. + +- [ ] **Step 2: Verify the helper path is still GUI-free** + +```bash +python3 -X importtime mount_manager.py --helper set-enabled --manager-id never --enabled 0 2>&1 | grep -E "gi\.repository\.(Gtk|Adw)" || echo "OK: no GUI imports" +``` + +Expected: prints `OK: no GUI imports`. (The command itself will fail with a "not found" error from the helper path — that's expected; we only care about the import trace.) + +- [ ] **Step 3: Final manual smoke** + +```bash +python3 mount_manager.py +``` + +Walk through one more time: + +1. Header-bar Add Share button: icon + label, no accent color. +2. Empty state: status page with `network-server-symbolic`, plain-text description, single suggested-action pill. +3. Open Add Share via `Ctrl+N`: path entry has focus, type a host, fill credentials, press Enter — submits. +4. Open About via menu: no duplicate developer name on the front page. +5. Delete a mount via the kebab menu: confirmation dialog button reads "Delete Share". Cancel. +6. `Ctrl+?` opens the shortcuts window. `Esc` closes it. + +- [ ] **Step 4: Confirm with the user** + +Stop here and tell the user the HIG-fix tasks are complete, all tests still pass, and the branch is ready to return to the `finishing-a-development-branch` flow (merge / push+PR / keep / discard). diff --git a/docs/superpowers/plans/2026-05-28-libadwaita-1.8-bump.md b/docs/superpowers/plans/2026-05-28-libadwaita-1.8-bump.md new file mode 100644 index 0000000..8311982 --- /dev/null +++ b/docs/superpowers/plans/2026-05-28-libadwaita-1.8-bump.md @@ -0,0 +1,476 @@ +# Libadwaita 1.8 Baseline Bump — Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Raise the minimum libadwaita to 1.8 and adopt the newer APIs it (and modern GTK) enable: `Adw.Spinner`, `Adw.ShortcutsDialog`, `Gtk.FileLauncher`, and `AdwPreferencesGroup.set_separate_rows()`. + +**Architecture:** Five small surgical changes on the `feat/libadwaita-01` branch. The version bump comes first (with its test-fixture rebase) so subsequent tasks legitimately depend on the new floor. Each subsequent task swaps a single API call site and gets its own commit. No new modules; no architectural change. + +**Tech Stack:** Python 3, GTK 4 (≥ 4.18 transitively), libadwaita ≥ 1.8, PyGObject. Tests: stock `unittest` (no pytest). + +**Source spec:** `docs/superpowers/specs/2026-05-28-libadwaita-1.8-bump-design.md` + +**Pre-flight (executor):** +- Confirm working tree is clean for tracked files (`git status` should show no `M` lines for `mount_manager.py`, `mount_manager_ui.py`, `README.md`, or `tests/`). +- Confirm the runtime libadwaita is at least 1.8: `python3 -c "import gi; gi.require_version('Adw','1'); from gi.repository import Adw; print(Adw.MAJOR_VERSION, Adw.MINOR_VERSION)"` should print `1 8` or higher. +- Baseline test run: `python3 -m unittest discover -s tests -v` should report 9 tests, all passing. + +--- + +## Task 1: Bump `MIN_LIBADWAITA_VERSION` to (1, 8) + +**Files:** +- Modify: `mount_manager.py:52-53` +- Modify: `tests/test_libadwaita_support.py` (full file) +- Modify: `README.md:27` + +This task is genuinely TDD-shaped: the version-support test file is the contract we're changing. Rebase the test fixtures first, watch them fail, then update the constant. + +- [ ] **Step 1: Rebase the test fixtures on the new (1, 8) floor** + +Replace the entire body of `tests/test_libadwaita_support.py` with: + +```python +"""Unit tests for the libadwaita version comparator.""" + +import unittest + +from mount_manager import _libadwaita_supports + + +class LibadwaitaSupportsTest(unittest.TestCase): + def test_minimum_supported_version(self) -> None: + self.assertTrue(_libadwaita_supports(1, 8)) + + def test_newer_minor_supported(self) -> None: + self.assertTrue(_libadwaita_supports(1, 9)) + + def test_newer_major_supported(self) -> None: + self.assertTrue(_libadwaita_supports(2, 0)) + + def test_older_minor_unsupported(self) -> None: + self.assertFalse(_libadwaita_supports(1, 7)) + + def test_older_major_unsupported(self) -> None: + self.assertFalse(_libadwaita_supports(0, 99)) + + +if __name__ == "__main__": + unittest.main() +``` + +- [ ] **Step 2: Run the tests, confirm the floor checks fail** + +Run: `python3 -m unittest discover -s tests -v` + +Expected: `test_minimum_supported_version` and `test_older_minor_unsupported` FAIL. +Specifically: `_libadwaita_supports(1, 8)` returns True under the new test but currently True anyway (since 1.8 >= 1.5), so that one will not fail. The real failure is `test_older_minor_unsupported` — `_libadwaita_supports(1, 7)` returns True under the old (1, 5) floor but the test now asserts False. + +(The minimum-version test continues to pass coincidentally; the older-minor test is the one that proves the change.) + +- [ ] **Step 3: Bump the version constant and comment** + +In `mount_manager.py`, replace lines 52–53: + +```python +# Adw.Dialog and Adw.AlertDialog require libadwaita 1.5 or newer. +MIN_LIBADWAITA_VERSION: tuple[int, int] = (1, 5) +``` + +with: + +```python +# Adw.ShortcutsDialog and Adw.Spinner require libadwaita 1.8 or newer. +MIN_LIBADWAITA_VERSION: tuple[int, int] = (1, 8) +``` + +- [ ] **Step 4: Run the tests, confirm all pass** + +Run: `python3 -m unittest discover -s tests -v` + +Expected: 9 tests, all pass. + +- [ ] **Step 5: Update the README** + +In `README.md` line 27, replace: + +``` +libadwaita 1.5 or newer. The app refuses to start on older versions. +``` + +with: + +``` +libadwaita 1.8 or newer. The app refuses to start on older versions. +``` + +- [ ] **Step 6: Smoke-launch the app** + +Run: `timeout 4 python3 mount_manager.py` (in a desktop session). The app should launch and show its main window. Close it (or let the timeout kill it). + +Expected: No "libadwaita too old" message. App reaches the main window. + +- [ ] **Step 7: Commit** + +```bash +git add mount_manager.py tests/test_libadwaita_support.py README.md +git commit -m "feat: raise minimum libadwaita to 1.8" +``` + +--- + +## Task 2: Swap `Gtk.Spinner` → `Adw.Spinner` + +**Files:** +- Modify: `mount_manager_ui.py` — `AddShareDialog.__init__` host_spinner construction; `AddShareDialog._set_host_status`; `AddShareDialog._run_host_check`. + +`Adw.Spinner` (libadwaita 1.6) spins whenever it is realized and visible. It has no `start()` / `stop()` methods — those calls become no-ops on `Adw.Spinner` and would raise `AttributeError`. Replace the construction call and delete the explicit `start()` / `stop()` calls. + +- [ ] **Step 1: Swap the construction call** + +In `mount_manager_ui.py`, locate (inside `AddShareDialog.__init__`): + +```python + self.host_spinner = Gtk.Spinner() +``` + +Replace with: + +```python + self.host_spinner = Adw.Spinner() +``` + +- [ ] **Step 2: Drop the `stop()` call in `_set_host_status`** + +In `_set_host_status`, locate: + +```python + def _set_host_status(self, *, ok: bool | None, message: str) -> None: + self.host_spinner.set_visible(False) + self.host_spinner.stop() +``` + +Replace with: + +```python + def _set_host_status(self, *, ok: bool | None, message: str) -> None: + self.host_spinner.set_visible(False) +``` + +- [ ] **Step 3: Drop the `start()` call in `_run_host_check`** + +In `_run_host_check`, locate: + +```python + self.host_spinner.set_visible(True) + self.host_spinner.start() +``` + +Replace with: + +```python + self.host_spinner.set_visible(True) +``` + +- [ ] **Step 4: Run the smoke test** + +Run: `python3 -m unittest discover -s tests -v` + +Expected: 9 tests, all pass. (The smoke test `test_import_mount_manager` will catch any import-level break.) + +- [ ] **Step 5: Manual verification (executor or user)** + +Launch: `python3 mount_manager.py` → click "Add Share" → type a hostname (e.g. `192.0.2.1`, an unroutable address). The spinner appears next to the share-path field while the host check is in flight, then disappears and is replaced by an error icon. No `AttributeError` in stderr. + +(If the executor cannot reach a desktop session, document the verification as deferred to the user and proceed.) + +- [ ] **Step 6: Commit** + +```bash +git add mount_manager_ui.py +git commit -m "refactor(ui): use Adw.Spinner in Add Share dialog" +``` + +--- + +## Task 3: Rewrite the shortcuts dialog using `Adw.ShortcutsDialog` + +**Files:** +- Modify: `mount_manager_ui.py` — `build_shortcuts_window()` (helper inside `run_gui()`); `MountManagerApplication._show_shortcuts()`. + +`Adw.ShortcutsDialog` (libadwaita 1.8) replaces the deprecated `Gtk.ShortcutsWindow`. It extends `Adw.Dialog` (so it presents via `.present(parent)`, not `transient_for=`). Items can specify `action_name=` and the dialog auto-resolves the accelerator from `set_accels_for_action()` registered on the application — so we no longer duplicate accelerator literals here. + +- [ ] **Step 1: Replace the helper function** + +In `mount_manager_ui.py`, locate the entire `build_shortcuts_window` function inside `run_gui()`: + +```python + def build_shortcuts_window(parent: Gtk.Window) -> Gtk.ShortcutsWindow: + """Construct the keyboard shortcuts dialog for the app.""" + window = Gtk.ShortcutsWindow(transient_for=parent, modal=True) + + section = Gtk.ShortcutsSection(section_name="main", visible=True) + + general = Gtk.ShortcutsGroup(title="General") + general.append( + Gtk.ShortcutsShortcut(title="Add Share", accelerator="n") + ) + general.append(Gtk.ShortcutsShortcut(title="Refresh", accelerator="r")) + general.append(Gtk.ShortcutsShortcut(title="Primary Menu", accelerator="F10")) + general.append( + Gtk.ShortcutsShortcut( + title="Keyboard Shortcuts", accelerator="question" + ) + ) + general.append( + Gtk.ShortcutsShortcut(title="Close Window", accelerator="w") + ) + general.append(Gtk.ShortcutsShortcut(title="Quit", accelerator="q")) + section.append(general) + + window.add_section(section) + return window +``` + +Replace with: + +```python + def build_shortcuts_dialog() -> Adw.ShortcutsDialog: + """Construct the keyboard shortcuts dialog for the app.""" + dialog = Adw.ShortcutsDialog() + + general = Adw.ShortcutsSection(title="General") + general.add(Adw.ShortcutsItem(title="Add Share", action_name="win.add-share")) + general.add(Adw.ShortcutsItem(title="Refresh", action_name="win.refresh")) + general.add(Adw.ShortcutsItem(title="Primary Menu", action_name="win.show-menu")) + general.add(Adw.ShortcutsItem(title="Keyboard Shortcuts", action_name="app.shortcuts")) + general.add(Adw.ShortcutsItem(title="Close Window", action_name="win.close")) + general.add(Adw.ShortcutsItem(title="Quit", action_name="app.quit")) + + dialog.add(general) + return dialog +``` + +(Note: the helper is renamed from `build_shortcuts_window` to `build_shortcuts_dialog` to match the new return type. Step 2 updates the only caller.) + +- [ ] **Step 2: Update `MountManagerApplication._show_shortcuts()`** + +In `mount_manager_ui.py`, locate (inside `MountManagerApplication`): + +```python + def _show_shortcuts(self) -> None: + window = self.props.active_window + if window is None: + return + shortcuts_window = build_shortcuts_window(window) + shortcuts_window.present() +``` + +Replace with: + +```python + def _show_shortcuts(self) -> None: + window = self.props.active_window + if window is None: + return + dialog = build_shortcuts_dialog() + dialog.present(window) +``` + +- [ ] **Step 3: Confirm no other references to the old name** + +Run: `grep -n "build_shortcuts_window\|Gtk.ShortcutsWindow\|Gtk.ShortcutsSection\|Gtk.ShortcutsGroup\|Gtk.ShortcutsShortcut" mount_manager_ui.py` + +Expected: no output. If anything matches, fix it before continuing. + +- [ ] **Step 4: Run the smoke test** + +Run: `python3 -m unittest discover -s tests -v` + +Expected: 9 tests, all pass. + +- [ ] **Step 5: Manual verification (executor or user)** + +Launch: `python3 mount_manager.py` → press `Ctrl+?`. A libadwaita-styled shortcuts dialog appears. Each row shows its accelerator (e.g. `Ctrl+N` next to "Add Share"); the accelerators are sourced automatically from `set_accels_for_action()`. No deprecation warnings in stderr. + +(If the executor cannot reach a desktop session, document the verification as deferred to the user and proceed.) + +- [ ] **Step 6: Commit** + +```bash +git add mount_manager_ui.py +git commit -m "refactor(ui): use Adw.ShortcutsDialog for keyboard shortcuts" +``` + +--- + +## Task 4: Swap `xdg-open` subprocess → `Gtk.FileLauncher` + +**Files:** +- Modify: `mount_manager_ui.py` — `MainWindow.open_mount_folder()`; possibly the `run_command` import at the top of the file. + +`Gtk.FileLauncher` (GTK 4.10) opens a file or folder with the desktop's default handler. It's async and reports failures via `GError` so we can distinguish user cancellation from real failures. + +- [ ] **Step 1: Rewrite `open_mount_folder` and add `_on_open_folder_done`** + +In `mount_manager_ui.py`, locate (inside `MainWindow`): + +```python + def open_mount_folder(self, record: ManagedMount) -> None: + if not record.mount_point.exists(): + self.show_toast(f"Mount folder does not exist: {record.mount_point}") + return + try: + run_command(["xdg-open", str(record.mount_point)]) + except MountManagerError as exc: + self.show_toast(f"Could not open {record.mount_point}: {exc}") +``` + +Replace with: + +```python + def open_mount_folder(self, record: ManagedMount) -> None: + if not record.mount_point.exists(): + self.show_toast(f"Mount folder does not exist: {record.mount_point}") + return + launcher = Gtk.FileLauncher.new(Gio.File.new_for_path(str(record.mount_point))) + launcher.launch(self, None, self._on_open_folder_done) + + def _on_open_folder_done( + self, launcher: Gtk.FileLauncher, result: Gio.AsyncResult + ) -> None: + try: + launcher.launch_finish(result) + except GLib.Error as exc: + if exc.matches(Gio.io_error_quark(), Gio.IOErrorEnum.CANCELLED): + return + self.show_toast(f"Could not open folder: {exc.message}") +``` + +- [ ] **Step 2: Check whether `run_command` is still used in `mount_manager_ui.py`** + +Run: `grep -n "run_command" mount_manager_ui.py` + +If the only remaining match is the import line at the top of the file, remove `run_command` from the import list. + +Locate (near the top of the file): + +```python +from mount_manager import ( + ... + run_command, + ... +) +``` + +If `run_command` is no longer referenced anywhere else in the file, delete the ` run_command,` line from the import. + +- [ ] **Step 3: Run the smoke test** + +Run: `python3 -m unittest discover -s tests -v` + +Expected: 9 tests, all pass. + +- [ ] **Step 4: Static check — confirm the new symbols are imported** + +Run: `grep -nE "^from gi.repository" mount_manager_ui.py` + +Expected: the line already imports `Gio`, `GLib`, and `Gtk`, so no import changes are needed for the new code. + +- [ ] **Step 5: Manual verification (executor or user)** + +Launch: `python3 mount_manager.py`. With at least one managed mount enabled, click its folder icon. The system file manager opens at the mount point. If you have no managed mounts handy, skip the visible part of this check — the `unittest` smoke test will have already caught any Python-level breakage. + +(If the executor cannot reach a desktop session, document the verification as deferred to the user and proceed.) + +- [ ] **Step 6: Commit** + +```bash +git add mount_manager_ui.py +git commit -m "refactor(ui): open mount folders with Gtk.FileLauncher" +``` + +--- + +## Task 5: Render mount rows as separate cards + +**Files:** +- Modify: `mount_manager_ui.py` — `MainWindow.__init__` mount group construction. + +`AdwPreferencesGroup.set_separate_rows(True)` (libadwaita 1.6) renders each row as its own boxed card instead of a single grouped container. The empty state is unaffected (the `AdwStatusPage` is shown in place of the group when no mounts exist). + +- [ ] **Step 1: Add the `set_separate_rows` call** + +In `mount_manager_ui.py`, locate (inside `MainWindow.__init__`): + +```python + self.mount_group = Adw.PreferencesGroup() + self.preferences_page.add(self.mount_group) +``` + +Replace with: + +```python + self.mount_group = Adw.PreferencesGroup() + self.mount_group.set_separate_rows(True) + self.preferences_page.add(self.mount_group) +``` + +- [ ] **Step 2: Run the smoke test** + +Run: `python3 -m unittest discover -s tests -v` + +Expected: 9 tests, all pass. + +- [ ] **Step 3: Manual verification (executor or user)** + +Launch: `python3 mount_manager.py`. With at least one managed mount listed, each mount renders as its own card row rather than as a list inside a single bordered container. + +(If the executor cannot reach a desktop session, document the verification as deferred to the user and proceed.) + +- [ ] **Step 4: Commit** + +```bash +git add mount_manager_ui.py +git commit -m "feat(ui): render mount rows as separate cards" +``` + +--- + +## Final verification + +After all five tasks are committed: + +- [ ] **Run the full test suite:** + +```bash +python3 -m unittest discover -s tests -v +``` + +Expected: 9 tests, all pass. + +- [ ] **Verify the helper path is still GUI-free:** + +```bash +python3 -X importtime mount_manager.py --helper set-enabled --manager-id never --enabled 0 2>&1 | grep -E "gi\.repository\.(Gtk|Adw)" +``` + +Expected: no matches. (Per `AGENTS.md`: the helper path must not import GTK/Adw.) + +The command will exit non-zero (the helper is unprivileged when not run via pkexec, so it'll bail) — that's expected. We only care that no GTK/Adw import showed up. + +- [ ] **Inspect commit history:** + +```bash +git log --oneline -n 5 +``` + +Expected: five new commits, one per task, on the `feat/libadwaita-01` branch. + +- [ ] **Verify no deprecation warnings when launching:** + +```bash +timeout 4 python3 mount_manager.py 2>&1 | grep -iE "deprecat|warning" || echo "OK — no deprecations" +``` + +Expected: `OK — no deprecations`. (In particular, the `Gtk.ShortcutsWindow.add_section` deprecation noted at the end of the HIG-fixes plan should no longer appear.) diff --git a/docs/superpowers/specs/2026-05-28-hig-fixes-design.md b/docs/superpowers/specs/2026-05-28-hig-fixes-design.md new file mode 100644 index 0000000..2e98b40 --- /dev/null +++ b/docs/superpowers/specs/2026-05-28-hig-fixes-design.md @@ -0,0 +1,224 @@ +# GNOME HIG audit — SMB Mount Manager + +Date: 2026-05-28 +Scope: Full sweep of the libadwaita UI on branch `feat/libadwaita-01`. +Reference: https://developer.gnome.org/hig/index.html + +Findings are organized by severity. Each cites the HIG page it draws from so it +can be split into individual GitHub issues without losing context. + +--- + +## Critical + +*(None.)* The app respects the big architectural HIG choices: `AdwApplicationWindow` ++ `AdwToolbarView` + `AdwToastOverlay`, hybrid `AdwActionRow` pattern, +`AdwStatusPage` empty state, `AdwAlertDialog` for destructive confirmation, +`AdwAboutDialog` with proper metadata, color scheme delegated to +`Adw.StyleManager`. + +--- + +## Major + +### M1. No keyboard shortcuts at all + +**HIG:** `guidelines/keyboard.html`, `reference/keyboard.html` + +Every common action should be keyboard-reachable and standard accelerators +should be wired up. Currently the app has zero accelerators. + +Missing, at minimum: + +- `Ctrl+W` — close window +- `Ctrl+Q` — quit +- `Ctrl+N` — Add Share (closest standard mapping for "create new item") +- `Ctrl+R` — refresh +- `F10` — primary menu +- `Ctrl+?` — Keyboard Shortcuts dialog + +And the supporting UI: + +- A `Gtk.ShortcutsWindow` describing the above. +- A "Keyboard Shortcuts" entry in the primary menu. + +Also: when the AddShareDialog opens, no widget has explicit initial focus +(see m5). + +### M2. Suggested-action label-only button in a primary-window header bar + +**HIG:** `patterns/containers/header-bars.html` → Button Style + +> Types of buttons which don't automatically have their appearance adjusted +> when in a header bar include buttons with: a text label only; +> the suggested and destructive action styles … These button types should +> generally be avoided for primary window header bars, since it leads to a +> complex and inconsistent visual appearance. + +The header-bar "Add Share" button has both attributes. Fix: + +- Add an icon (e.g. `list-add-symbolic`) so the button is icon+label. +- Drop the `suggested-action` CSS class on the header copy. +- Keep the empty-state pill button as the lone suggested-action CTA. + +### M3. Two suggested-action buttons visible simultaneously in the empty state + +**HIG:** `patterns/controls/buttons.html` → Suggested & Destructive Actions + +> Each view should only ever include a single button using either the +> suggested or destructive styles. + +In the empty state, both the header-bar "Add Share" and the pill "Add Share" +on the `AdwStatusPage` carry `suggested-action`. Fixing M2 (drop suggested +from the header button) also fixes this. + +--- + +## Minor + +### m1. Toast titles end with periods + +**HIG:** `guidelines/writing-style.html` → Periods; `patterns/feedback/toasts.html` → +toasts use the informal heading style. + +> Text generally shouldn't end with a period. + +Affected strings in `mount_manager_ui.py`: + +- `f"{share} added."` +- `f"{record.source} removed."` +- `f"{record.source} upgraded."` +- All `f"… failed: {exc}"` toasts and the "Mount folder does not exist: …" toast. + +Drop the trailing period from every toast title. + +### m2. Empty-state description uses Pango italics + +`empty_page.set_description("Click Add Share to mount one.")` renders the +button name in italics. Italic emphasis is not an HIG pattern for +`AdwStatusPage` descriptions. Use plain text: + +> `Click "Add Share" to mount one` + +(Note: also drop the trailing period per m1.) + +### m3. Header-bar "Add Share" tooltip duplicates the label + +**HIG:** Tooltips should add information, not echo the label. + +Current: button label `"Add Share"`, tooltip `"Add share"`. Either remove the +tooltip or change it to add value — e.g. `"Mount a new SMB share"`. + +### m4. Primary menu tooltip says "Main menu" + +**HIG:** standard terminology is "Primary menu." Change the +`open-menu-symbolic` `MenuButton` tooltip from `"Main menu"` to +`"Primary menu"`. + +### m5. AddShareDialog does not set a default widget / initial focus + +**HIG:** `patterns/feedback/dialogs.html` + +> Assign the return key to activate the affirmative button. However, this +> should not be done if its action is irreversible, destructive or otherwise +> inconvenient to the user. +> When opening a dialog, provide initial keyboard focus to the component that +> you expect users to operate first. + +Currently neither is done. Add: + +- `self.set_default_widget(self.add_button)` so Enter in the password field + submits. +- Explicit focus on `self.path_row` when the dialog presents. + +### m6. AlertDialog affirmative button labelled "Delete" + +**HIG:** `patterns/feedback/dialogs.html` + +> Label the affirmative button with a specific imperative verb. + +Borderline — the dialog heading ("Delete this SMB mount?") carries the object. +`"Delete Share"` or `"Remove Mount"` is more in line with the guideline. Low +priority; mention if revisiting that dialog. + +### m7. Mount group title `"SMB Shares"` duplicates the window title context + +The window is already "SMB Mount Manager." Single-group preferences pages +typically omit the group title, or use a neutral one. Consider dropping it or +renaming to `"Mounts"`. + +--- + +## Nits + +### n1. Legacy icon names + +`emblem-ok-symbolic` → `checkmark-symbolic` +`dialog-error-symbolic` → `error-symbolic` + +Both legacy names still resolve; the new names are more idiomatic in fresh +GTK4 / libadwaita code. + +### n2. Empty-state icon + +`folder-remote-symbolic` is fine but `network-server-symbolic` is arguably a +better match for SMB. Subjective. + +### n3. Redundant calls in AddShareDialog header + +`self._header.set_show_start_title_buttons(False)` and +`set_show_end_title_buttons(False)` are redundant — `AdwDialog` already manages +its title-bar buttons. + +### n4. About dialog has overlapping developer fields + +`AdwAboutDialog` is constructed with both +`developer_name=APP_DEVELOPERS[0]` and then `set_developers(APP_DEVELOPERS)`. +Both end up populated; pick one form per role (`developer_name` is the +single-line credit, `developers` is the list shown on the credits page). + +--- + +## Intentionally non-compliant (justified) + +### Destructive Delete uses confirmation, not undo + +**HIG:** `patterns/feedback/dialogs.html` → Confirmation Dialogs + +> Undo is typically a better option than a confirmation dialog. + +Undoing delete here would require re-creating the systemd units and +re-decrypting credentials — non-trivial. Confirmation is the right call. Worth +being explicit in the code so future contributors understand why this path was +chosen. + +--- + +## Strengths (for completeness) + +- `AdwApplicationWindow` + `AdwToolbarView` + `AdwToastOverlay` shell. +- Hybrid `AdwActionRow` pattern (switch + single inline suffix + kebab menu). +- `AdwStatusPage` empty state with a clear primary CTA. +- `AdwAlertDialog` with `DESTRUCTIVE` response appearance, `cancel` set as both + default and close response. +- `AdwAboutDialog` with developers, website, issue URL, license type. +- Color scheme delegated to `Adw.StyleManager.ColorScheme.DEFAULT` (respects + system preference; no custom CSS). +- Debounced host check with `Gio.Cancellable` and explicit `GLib.source_remove` + on dialog close — no race between debounce, worker thread, and dialog + teardown. +- All user-controlled strings escaped with `GLib.markup_escape_text` before + being rendered as Pango markup. + +--- + +## Suggested ordering when filing issues + +1. M1 — keyboard shortcuts + shortcuts window (largest accessibility gap) +2. M2 + M3 — header-bar Add Share style (small fix, fixes both) +3. m1 — toast period sweep +4. m2 — empty-state description +5. m3 + m4 — tooltip copy +6. m5 — AddShareDialog default widget + initial focus +7. m6, m7 — copy refinements +8. n1–n4 — opportunistic cleanups diff --git a/docs/superpowers/specs/2026-05-28-libadwaita-1.8-bump-design.md b/docs/superpowers/specs/2026-05-28-libadwaita-1.8-bump-design.md new file mode 100644 index 0000000..e5cb353 --- /dev/null +++ b/docs/superpowers/specs/2026-05-28-libadwaita-1.8-bump-design.md @@ -0,0 +1,284 @@ +# Libadwaita 1.8 Baseline Bump — Design + +**Date:** 2026-05-28 +**Branch:** `feat/libadwaita-01` (pre-merge) +**Status:** Approved by user; ready for implementation plan. + +## Goal + +Raise the minimum libadwaita to 1.8 and opportunistically adopt newer APIs +made possible by the bump (`Adw.Spinner`, `Adw.ShortcutsDialog`). Also +modernize the "open folder" path off `xdg-open` onto `Gtk.FileLauncher` +(GTK 4.10) while we're touching the stack. This keeps the floor in line +with current GNOME, clears the accepted `Gtk.ShortcutsWindow` deprecation +noted at the end of the HIG-fixes plan, and removes a subprocess wart. + +## Scope + +Five coupled changes: + +1. **Bump the floor.** `MIN_LIBADWAITA_VERSION: tuple[int, int] = (1, 5)` → + `(1, 8)` in `mount_manager.py`. Update the comment above it (currently + "Adw.Dialog and Adw.AlertDialog require libadwaita 1.5 or newer") to + reflect what 1.8 buys us. + +2. **`Gtk.Spinner` → `Adw.Spinner`** (libadwaita 1.6) inside + `AddShareDialog`. `Adw.Spinner` spins whenever it is visible, so the + `start()` / `stop()` calls in `_set_host_status` and `_run_host_check` can + be deleted entirely — `set_visible(True/False)` is sufficient. + +3. **`Gtk.ShortcutsWindow` family → `Adw.ShortcutsDialog` family** + (libadwaita 1.8) inside `build_shortcuts_window()`. The replacement uses + `Adw.ShortcutsDialog.add(section)` with `Adw.ShortcutsSection(title=...)` + containing `Adw.ShortcutsItem` children. The new API lets each item refer + to an action by name (`action_name="app.quit"`) and libadwaita + auto-discovers the accelerator from `set_accels_for_action`, so we no + longer have to repeat each accelerator literal. Resolves the deprecation + note from Task 6 of the HIG-fixes plan. + +4. **`xdg-open` subprocess → `Gtk.FileLauncher`** (GTK 4.10) inside + `MainWindow.open_mount_folder()`. The current implementation shells out + to `xdg-open` via `run_command`, which collapses every failure mode + into a generic `MountManagerError`. `Gtk.FileLauncher.launch()` is + async, integrates with the desktop's URI launcher (and portals where + applicable), and reports failure via a proper `GError` we can show as a + toast. + +5. **`AdwPreferencesGroup.set_separate_rows(True)`** (libadwaita 1.6) on + the mount list group in `MainWindow`. Renders each mount as its own + boxed card row instead of a single grouped container. Visually + confirmed to read better than the grouped style for this list. One + line in `MainWindow.__init__`. No change needed for the empty state + (the `AdwStatusPage` is shown instead of the group when there are no + mounts). + +## Out of scope + +- Adoption of any other 1.6–1.8 API (`AdwBottomSheet`, `AdwMultiLayoutView`, + `AdwInlineViewSwitcher`, `AdwButtonRow`, `AdwToggleGroup`). These have no + current pull from the codebase and will be considered as needs arise. +- Refactoring the hybrid `AdwActionRow` mount-row pattern to use + `AdwSwitchRow`. The hybrid pattern was a deliberate design choice from + the libadwaita migration; switching now would unwind that. Out of scope. + +## Files touched + +| File | Change | +|------|--------| +| `mount_manager.py` | Version constant + the comment above it. ~2 lines. | +| `mount_manager_ui.py` | `Adw.Spinner` swap (~3 lines, net simpler). `build_shortcuts_window()` rewrite (~30 lines net). `open_mount_folder()` swap to `Gtk.FileLauncher` (~10 lines). `mount_group.set_separate_rows(True)` (1 line). | +| `README.md` | "libadwaita 1.5 or newer" → "libadwaita 1.8 or newer" (line 27). | +| `tests/test_libadwaita_support.py` | Rebase fixture values on `(1, 8)` — e.g. `older_minor=(1, 7)`, `newer_minor=(1, 9)`, `newer_major=(2, 0)`, etc. | +| `AGENTS.md` | No change. It already says `MIN_LIBADWAITA_VERSION` is the single source of truth and never hardcodes a number. | + +## Detailed API notes + +### Adw.Spinner (1.6) + +`Adw.Spinner` is a `Gtk.Widget` subclass with no methods of its own +(inherited GObject only). It spins continuously when realized and visible. +No `start()` / `stop()`. Sizing follows allocation, never smaller than +16×16, never larger than 64×64. As an `EntryRow` suffix the row's natural +height will allocate appropriately; no `width-request`/`height-request` +needed. + +Current usage in `AddShareDialog`: + +```python +self.host_spinner = Gtk.Spinner() +self.host_spinner.set_valign(Gtk.Align.CENTER) +self.host_spinner.set_visible(False) +self.path_row.add_suffix(self.host_spinner) +# … +self.host_spinner.set_visible(False) +self.host_spinner.stop() +# … +self.host_spinner.set_visible(True) +self.host_spinner.start() +``` + +After: + +```python +self.host_spinner = Adw.Spinner() +self.host_spinner.set_valign(Gtk.Align.CENTER) +self.host_spinner.set_visible(False) +self.path_row.add_suffix(self.host_spinner) +# … +self.host_spinner.set_visible(False) +# … +self.host_spinner.set_visible(True) +``` + +### Adw.ShortcutsDialog (1.8) + +`Adw.ShortcutsDialog` extends `Adw.Dialog` (so it presents via `.present(parent)`, +not `transient_for=`). Sections are added with `dialog.add(section)`. Items +within a section can specify either `accelerator=` (literal) or +`action_name=` (auto-resolves the accelerator from +`set_accels_for_action`). + +Current usage in `build_shortcuts_window()`: + +```python +window = Gtk.ShortcutsWindow(transient_for=parent, modal=True) +section = Gtk.ShortcutsSection(section_name="main", visible=True) +general = Gtk.ShortcutsGroup(title="General") +general.add_shortcut(Gtk.ShortcutsShortcut(title="Add Share", accelerator="n")) +# … five more shortcuts with literal accelerators … +section.add_group(general) +window.add_section(section) +return window +``` + +After (new function name reflects the new return type): + +```python +def build_shortcuts_dialog() -> Adw.ShortcutsDialog: + """Construct the keyboard shortcuts dialog for the app.""" + dialog = Adw.ShortcutsDialog() + + general = Adw.ShortcutsSection(title="General") + general.add(Adw.ShortcutsItem(title="Add Share", action_name="win.add-share")) + general.add(Adw.ShortcutsItem(title="Refresh", action_name="win.refresh")) + general.add(Adw.ShortcutsItem(title="Primary Menu", action_name="win.show-menu")) + general.add(Adw.ShortcutsItem(title="Keyboard Shortcuts", action_name="app.shortcuts")) + general.add(Adw.ShortcutsItem(title="Close Window", action_name="win.close")) + general.add(Adw.ShortcutsItem(title="Quit", action_name="app.quit")) + + dialog.add(general) + return dialog +``` + +The `_show_shortcuts()` method in `MountManagerApplication` changes from +`shortcuts_window.present()` (no parent) to +`shortcuts_dialog.present(window)` (AdwDialog requires a parent): + +```python +def _show_shortcuts(self) -> None: + window = self.props.active_window + if window is None: + return + dialog = build_shortcuts_dialog() + dialog.present(window) +``` + +**Action-name auto-discovery prerequisites:** The actions +(`win.add-share`, `win.refresh`, `win.show-menu`, `win.close`, +`app.shortcuts`, `app.quit`) and their accelerators must already be +registered via `set_accels_for_action()` before the dialog is built. +They are — both `MountManagerApplication.__init__` (`app.*`) and +`MainWindow.__init__` (`win.*`) run before any `Ctrl+?` press. + +### Gtk.FileLauncher (GTK 4.10) + +`Gtk.FileLauncher` opens a file or folder with the desktop's default +handler. Constructed from a `Gio.File`, launched async with a parent +window for modality, completed via a `GAsyncReadyCallback`. Errors come +back as `GError` from `launch_finish()`, so we get distinct failure +reasons (cancelled, no handler, permission denied) instead of a single +`MountManagerError` from a subprocess exit code. + +Current usage in `MainWindow.open_mount_folder`: + +```python +def open_mount_folder(self, record: ManagedMount) -> None: + if not record.mount_point.exists(): + self.show_toast(f"Mount folder does not exist: {record.mount_point}") + return + try: + run_command(["xdg-open", str(record.mount_point)]) + except MountManagerError as exc: + self.show_toast(f"Could not open {record.mount_point}: {exc}") +``` + +After: + +```python +def open_mount_folder(self, record: ManagedMount) -> None: + if not record.mount_point.exists(): + self.show_toast(f"Mount folder does not exist: {record.mount_point}") + return + launcher = Gtk.FileLauncher.new(Gio.File.new_for_path(str(record.mount_point))) + launcher.launch(self, None, self._on_open_folder_done) + +def _on_open_folder_done( + self, launcher: Gtk.FileLauncher, result: Gio.AsyncResult +) -> None: + try: + launcher.launch_finish(result) + except GLib.Error as exc: + # Gio.IOErrorEnum.CANCELLED is the user dismissing a portal/handler + # dialog; not worth a toast. + if exc.matches(Gio.io_error_quark(), Gio.IOErrorEnum.CANCELLED): + return + self.show_toast(f"Could not open folder: {exc.message}") +``` + +The `run_command` import in `mount_manager_ui.py` may become unused — drop +it if so. `Gtk.FileLauncher` was introduced in GTK 4.10; our minimum +libadwaita 1.8 transitively requires GTK ≥ 4.18 (libadwaita 1.8's hard +floor), so this is always available. + +## Distribution impact + +Libadwaita 1.8 was released in September 2025. As of May 2026 the floor +covers: + +- Fedora 43+ (current release) +- Ubuntu 25.10+ +- Rolling distros (Arch, openSUSE Tumbleweed) +- Flatpak runtime 48 +- AppImage users: unaffected — `packaging/build-appimage.sh` bundles + libadwaita into the AppImage at build time + +Users on Fedora ≤ 42, Ubuntu LTS 24.04 or 25.04 will see the version-gate +error and must use the AppImage or a newer distro. Acceptable cost per +user direction (the branch has not landed in any production release). + +## Testing + +- Stock `unittest` only, per `AGENTS.md`. No new test dependencies. +- `tests/test_libadwaita_support.py` fixture values rebased on `(1, 8)`. + All five existing test cases (`test_minimum_supported_version`, + `test_newer_major_supported`, `test_newer_minor_supported`, + `test_older_major_unsupported`, `test_older_minor_unsupported`) keep + their shape — only the numeric inputs change. +- Widget construction is verified manually per `AGENTS.md`. The smoke + test (`test_import_mount_manager`) will catch any Python-level breakage + in the spinner and dialog rewrites. + +Manual verification checklist for the user: + +1. App launches; no "libadwaita too old" message. +2. Add Share → type a host → spinner spins while resolving, disappears + when the check completes; check icon appears for reachable host, error + icon for unreachable. +3. `Ctrl+?` opens a libadwaita-styled shortcuts dialog (note: visually + distinct from the old `Gtk.ShortcutsWindow` look). Each row shows its + accelerator badge sourced from `set_accels_for_action`. +4. No deprecation warnings appear in stderr when running the app. +5. With at least one managed mount enabled, click the folder icon → the + system file manager opens at the mount point. Dismissing any portal + dialog does not produce a toast; a real failure (e.g. mount point + removed mid-click) does. +6. Mount list rows render as separate cards (one boxed row per mount) + rather than a single grouped container. + +## Risks / open questions + +- **None blocking.** API surface confirmed against current libadwaita + documentation. Action-name auto-discovery is the only non-obvious + mechanism and its prerequisites are already satisfied by the existing + code structure. + +## Reference + +- Libadwaita ShortcutsDialog docs: + https://gnome.pages.gitlab.gnome.org/libadwaita/doc/main/class.ShortcutsDialog.html +- Libadwaita Spinner docs: + https://gnome.pages.gitlab.gnome.org/libadwaita/doc/main/class.Spinner.html +- HIG-fixes plan (notes the deprecation this spec resolves): + `docs/superpowers/plans/2026-05-28-hig-fixes.md` Task 6 +- Original migration design (for context on hybrid row pattern, etc.): + `docs/superpowers/specs/2026-05-28-libadwaita-migration-design.md` From e599875bc99db1cdbb75499930d40f0fab84f333 Mon Sep 17 00:00:00 2001 From: meowtypes Date: Thu, 28 May 2026 14:42:28 -0700 Subject: [PATCH 34/41] docs: move plans/ and specs/ up one directory level --- AGENTS.md | 4 ++-- docs/{superpowers => }/plans/2026-05-28-hig-fixes.md | 0 .../{superpowers => }/plans/2026-05-28-libadwaita-1.8-bump.md | 2 +- .../plans/2026-05-28-libadwaita-migration.md | 2 +- docs/{superpowers => }/specs/2026-05-28-hig-fixes-design.md | 0 .../specs/2026-05-28-libadwaita-1.8-bump-design.md | 4 ++-- .../specs/2026-05-28-libadwaita-migration-design.md | 0 7 files changed, 6 insertions(+), 6 deletions(-) rename docs/{superpowers => }/plans/2026-05-28-hig-fixes.md (100%) rename docs/{superpowers => }/plans/2026-05-28-libadwaita-1.8-bump.md (99%) rename docs/{superpowers => }/plans/2026-05-28-libadwaita-migration.md (99%) rename docs/{superpowers => }/specs/2026-05-28-hig-fixes-design.md (100%) rename docs/{superpowers => }/specs/2026-05-28-libadwaita-1.8-bump-design.md (98%) rename docs/{superpowers => }/specs/2026-05-28-libadwaita-migration-design.md (100%) diff --git a/AGENTS.md b/AGENTS.md index 5250cd8..cd004b9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -68,8 +68,8 @@ The application is split across two files: ## Reference docs -- Design spec: `docs/superpowers/specs/2026-05-28-libadwaita-migration-design.md` -- Implementation plan (executed, kept for context): `docs/superpowers/plans/2026-05-28-libadwaita-migration.md` +- Design spec: `docs/specs/2026-05-28-libadwaita-migration-design.md` +- Implementation plan (executed, kept for context): `docs/plans/2026-05-28-libadwaita-migration.md` ## Working rules - Prefer native tools (view/edit/create/grep/glob) over shell for file reading, editing, and diff --git a/docs/superpowers/plans/2026-05-28-hig-fixes.md b/docs/plans/2026-05-28-hig-fixes.md similarity index 100% rename from docs/superpowers/plans/2026-05-28-hig-fixes.md rename to docs/plans/2026-05-28-hig-fixes.md diff --git a/docs/superpowers/plans/2026-05-28-libadwaita-1.8-bump.md b/docs/plans/2026-05-28-libadwaita-1.8-bump.md similarity index 99% rename from docs/superpowers/plans/2026-05-28-libadwaita-1.8-bump.md rename to docs/plans/2026-05-28-libadwaita-1.8-bump.md index 8311982..ae44b50 100644 --- a/docs/superpowers/plans/2026-05-28-libadwaita-1.8-bump.md +++ b/docs/plans/2026-05-28-libadwaita-1.8-bump.md @@ -8,7 +8,7 @@ **Tech Stack:** Python 3, GTK 4 (≥ 4.18 transitively), libadwaita ≥ 1.8, PyGObject. Tests: stock `unittest` (no pytest). -**Source spec:** `docs/superpowers/specs/2026-05-28-libadwaita-1.8-bump-design.md` +**Source spec:** `docs/specs/2026-05-28-libadwaita-1.8-bump-design.md` **Pre-flight (executor):** - Confirm working tree is clean for tracked files (`git status` should show no `M` lines for `mount_manager.py`, `mount_manager_ui.py`, `README.md`, or `tests/`). diff --git a/docs/superpowers/plans/2026-05-28-libadwaita-migration.md b/docs/plans/2026-05-28-libadwaita-migration.md similarity index 99% rename from docs/superpowers/plans/2026-05-28-libadwaita-migration.md rename to docs/plans/2026-05-28-libadwaita-migration.md index 3c27b8a..f25e1bd 100644 --- a/docs/superpowers/plans/2026-05-28-libadwaita-migration.md +++ b/docs/plans/2026-05-28-libadwaita-migration.md @@ -8,7 +8,7 @@ **Tech Stack:** Python 3, PyGObject (`gi`), GTK 4, libadwaita ≥ 1.5, stdlib `unittest` for tests. -**Spec reference:** `docs/superpowers/specs/2026-05-28-libadwaita-migration-design.md` +**Spec reference:** `docs/specs/2026-05-28-libadwaita-migration-design.md` ## Testing strategy diff --git a/docs/superpowers/specs/2026-05-28-hig-fixes-design.md b/docs/specs/2026-05-28-hig-fixes-design.md similarity index 100% rename from docs/superpowers/specs/2026-05-28-hig-fixes-design.md rename to docs/specs/2026-05-28-hig-fixes-design.md diff --git a/docs/superpowers/specs/2026-05-28-libadwaita-1.8-bump-design.md b/docs/specs/2026-05-28-libadwaita-1.8-bump-design.md similarity index 98% rename from docs/superpowers/specs/2026-05-28-libadwaita-1.8-bump-design.md rename to docs/specs/2026-05-28-libadwaita-1.8-bump-design.md index e5cb353..abdfd86 100644 --- a/docs/superpowers/specs/2026-05-28-libadwaita-1.8-bump-design.md +++ b/docs/specs/2026-05-28-libadwaita-1.8-bump-design.md @@ -279,6 +279,6 @@ Manual verification checklist for the user: - Libadwaita Spinner docs: https://gnome.pages.gitlab.gnome.org/libadwaita/doc/main/class.Spinner.html - HIG-fixes plan (notes the deprecation this spec resolves): - `docs/superpowers/plans/2026-05-28-hig-fixes.md` Task 6 + `docs/plans/2026-05-28-hig-fixes.md` Task 6 - Original migration design (for context on hybrid row pattern, etc.): - `docs/superpowers/specs/2026-05-28-libadwaita-migration-design.md` + `docs/specs/2026-05-28-libadwaita-migration-design.md` diff --git a/docs/superpowers/specs/2026-05-28-libadwaita-migration-design.md b/docs/specs/2026-05-28-libadwaita-migration-design.md similarity index 100% rename from docs/superpowers/specs/2026-05-28-libadwaita-migration-design.md rename to docs/specs/2026-05-28-libadwaita-migration-design.md From 2f0c9bcbaad10b045e5d7c0b05072c799db31197 Mon Sep 17 00:00:00 2001 From: meowtypes Date: Thu, 28 May 2026 15:14:48 -0700 Subject: [PATCH 35/41] build: re-anchor appimage-helper.patch after refactors --- packaging/appimage-helper.patch | 44 ++++++++++++++++----------------- 1 file changed, 21 insertions(+), 23 deletions(-) diff --git a/packaging/appimage-helper.patch b/packaging/appimage-helper.patch index dfe2bb6..c094dad 100644 --- a/packaging/appimage-helper.patch +++ b/packaging/appimage-helper.patch @@ -1,10 +1,14 @@ diff --git a/mount-manager b/mount-manager --- a/mount-manager +++ b/mount-manager -@@ -1019,18 +1019,51 @@ - return "light" +@@ -921,18 +921,51 @@ + return displayed +-def run_privileged_helper(action: str, payload: dict[str, Any]) -> dict[str, Any]: +- pkexec = shutil.which("pkexec") +- if pkexec is None: +- raise CommandError("pkexec was not found. Install polkit to manage mounts.") +def appimage_helper_path(env: dict[str, str] | None = None, source_path: Path | None = None) -> str | None: + """Return the original AppImage path when running from an AppImage mount.""" + if env is None: @@ -24,7 +28,8 @@ diff --git a/mount-manager b/mount-manager + + return appimage + -+ + +- command = [ +def privileged_helper_command(pkexec: str, action: str) -> list[str]: + appimage = appimage_helper_path() + if appimage is not None: @@ -36,26 +41,19 @@ diff --git a/mount-manager b/mount-manager + ] + + return [ -+ pkexec, -+ sys.executable, -+ str(Path(__file__).resolve()), -+ "--helper", -+ action, -+ ] -+ -+ - def run_privileged_helper(action: str, payload: dict[str, Any]) -> dict[str, Any]: - pkexec = shutil.which("pkexec") - if pkexec is None: - raise CommandError("pkexec was not found. Install polkit to manage mounts.") - -- command = [ -- pkexec, -- sys.executable, -- str(Path(__file__).resolve()), -- "--helper", -- action, -- ] + pkexec, + sys.executable, + str(Path(__file__).resolve()), + "--helper", + action, + ] ++ ++ ++def run_privileged_helper(action: str, payload: dict[str, Any]) -> dict[str, Any]: ++ pkexec = shutil.which("pkexec") ++ if pkexec is None: ++ raise CommandError("pkexec was not found. Install polkit to manage mounts.") ++ + command = privileged_helper_command(pkexec, action) result = subprocess.run( command, From 6f7a00218f4414bf95a4370dfe035556f2f66853 Mon Sep 17 00:00:00 2001 From: meowtypes Date: Thu, 28 May 2026 15:26:41 -0700 Subject: [PATCH 36/41] fix(packaging): install mount_manager.py under its real name mount_manager_ui.py does 'from mount_manager import ...', which failed in the built AppImage because the build script installed mount_manager.py as 'mount-manager' (renamed, no .py extension, hyphenated -- unimportable as a Python module). Install it under its real filename and create a 'mount-manager' symlink for the AppRun entry point. Retarget the helper patch to mount_manager.py accordingly. --- AGENTS.md | 13 ++++++++----- packaging/appimage-helper.patch | 6 +++--- packaging/build-appimage.sh | 3 ++- 3 files changed, 13 insertions(+), 9 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index cd004b9..afa4793 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -55,12 +55,15 @@ The application is split across two files: ## Packaging -- `packaging/build-appimage.sh` installs both `mount_manager.py` (as `mount-manager`) and - `mount_manager_ui.py` (verbatim filename) into `$appdir/usr/bin/`. Python's - `sys.path[0]` covers the script directory, so the bare `import mount_manager_ui` in the - GUI shim resolves without `sys.path` manipulation. +- `packaging/build-appimage.sh` installs both `mount_manager.py` and `mount_manager_ui.py` + into `$appdir/usr/bin/` under their real filenames, then creates a `mount-manager` + symlink pointing at `mount_manager.py` for the AppRun entry point. The real filenames + matter: `mount_manager_ui.py` does `from mount_manager import …`, so the file backing + that module must be named `mount_manager.py` on disk. Python's `sys.path[0]` covers the + script directory, so both imports resolve without `sys.path` manipulation. - `packaging/appimage-helper.patch` rewrites the helper invocation so the AppImage - re-execs itself under `pkexec`. Do not change the helper CLI surface + re-execs itself under `pkexec`. It targets `mount_manager.py` (the installed filename), + not the `mount-manager` symlink. Do not change the helper CLI surface (`--helper {create|delete|upgrade|set-enabled}`) without updating this patch. - If you add a new top-level Python module that the GUI imports, you must add a matching `install` line in `packaging/build-appimage.sh` AND in the README's manual-install diff --git a/packaging/appimage-helper.patch b/packaging/appimage-helper.patch index c094dad..d9437c1 100644 --- a/packaging/appimage-helper.patch +++ b/packaging/appimage-helper.patch @@ -1,6 +1,6 @@ -diff --git a/mount-manager b/mount-manager ---- a/mount-manager -+++ b/mount-manager +diff --git a/mount_manager.py b/mount_manager.py +--- a/mount_manager.py ++++ b/mount_manager.py @@ -921,18 +921,51 @@ return displayed diff --git a/packaging/build-appimage.sh b/packaging/build-appimage.sh index b495770..b5f2a59 100755 --- a/packaging/build-appimage.sh +++ b/packaging/build-appimage.sh @@ -87,7 +87,7 @@ mkdir -p "$appdir/usr/share/licenses/$APP_ID" mkdir -p "$appdir/usr/share/metainfo" mkdir -p "$dist_dir" -install -D -m 0755 "$repo_root/mount_manager.py" "$appdir/usr/bin/mount-manager" +install -D -m 0755 "$repo_root/mount_manager.py" "$appdir/usr/bin/mount_manager.py" install -D -m 0644 "$repo_root/mount_manager_ui.py" "$appdir/usr/bin/mount_manager_ui.py" if ! command -v git >/dev/null 2>&1; then echo "git is required to apply the AppImage helper workaround." >&2 @@ -97,6 +97,7 @@ fi cd "$appdir/usr/bin" GIT_DIR= GIT_WORK_TREE=. git apply --no-index --quiet "$repo_root/packaging/appimage-helper.patch" ) +ln -sf mount_manager.py "$appdir/usr/bin/mount-manager" install -D -m 0644 "$repo_root/data/icons/hicolor/scalable/apps/$APP_ID.svg" \ "$appdir/usr/share/icons/hicolor/scalable/apps/$APP_ID.svg" install -D -m 0644 "$repo_root/data/metainfo/$APP_ID.metainfo.xml" \ From 15ac05a76bcbbecefbd1594038b7faeda5c03169 Mon Sep 17 00:00:00 2001 From: meowtypes Date: Sat, 30 May 2026 06:09:03 -0700 Subject: [PATCH 37/41] fmt: pep8 fmt sweep --- mount_manager.py | 4 +- mount_manager_ui.py | 140 +++++++++++++++++++------------ tests/test_libadwaita_support.py | 12 +-- 3 files changed, 93 insertions(+), 63 deletions(-) diff --git a/mount_manager.py b/mount_manager.py index da4b761..f36bef3 100644 --- a/mount_manager.py +++ b/mount_manager.py @@ -9,8 +9,6 @@ mode through pkexec so only the system-changing work runs as root. """ -from __future__ import annotations - import argparse import dataclasses import hashlib @@ -53,7 +51,7 @@ MIN_LIBADWAITA_VERSION: tuple[int, int] = (1, 8) -def _libadwaita_supports(major: int, minor: int) -> bool: +def libadwaita_supports(major: int, minor: int) -> bool: """Return True if the given libadwaita (major, minor) meets the app's minimum.""" return (major, minor) >= MIN_LIBADWAITA_VERSION diff --git a/mount_manager_ui.py b/mount_manager_ui.py index 1a39331..6ce5581 100644 --- a/mount_manager_ui.py +++ b/mount_manager_ui.py @@ -5,28 +5,12 @@ GTK when invoked with ``--helper``. """ -from __future__ import annotations - import sys import threading -from typing import Any - import gi - gi.require_version("Adw", "1") gi.require_version("Gdk", "4.0") gi.require_version("Gtk", "4.0") -from gi.repository import Adw, Gdk, Gio, GLib, Gtk # noqa: E402 - - -def GLib_markup_escape(text: str) -> str: - """Escape Pango markup characters in row titles/subtitles.""" - return GLib.markup_escape_text(text, -1) - - -def GLib_VariantType(spec: str) -> GLib.VariantType: - return GLib.VariantType.new(spec) - from mount_manager import ( APP_DEVELOPERS, APP_ICON_NAME, @@ -38,7 +22,7 @@ def GLib_VariantType(spec: str) -> GLib.VariantType: ManagedMount, MountManagerError, SharePath, - _libadwaita_supports, + libadwaita_supports, check_smb_host_reachable, load_displayed_mounts, request_helper_create, @@ -47,28 +31,45 @@ def GLib_VariantType(spec: str) -> GLib.VariantType: request_helper_upgrade, validate_credentials, ) +from gi.repository import ( + Adw, + Gdk, + Gio, + GLib, + Gtk +) + + +def GLib_markup_escape(text: str) -> str: + """Escape Pango markup characters in row titles/subtitles.""" + return GLib.markup_escape_text(text, -1) + + +def GLib_VariantType(spec: str) -> GLib.VariantType: + return GLib.VariantType.new(spec) def ensure_libadwaita_supported() -> None: """Print an error and raise SystemExit if libadwaita is too old.""" - if not _libadwaita_supports(Adw.MAJOR_VERSION, Adw.MINOR_VERSION): + if not libadwaita_supports(Adw.MAJOR_VERSION, Adw.MINOR_VERSION): required = ".".join(str(v) for v in MIN_LIBADWAITA_VERSION) found = f"{Adw.MAJOR_VERSION}.{Adw.MINOR_VERSION}" print( - f"libadwaita {found} found, but this app requires {required} or newer.", + f"libadwaita {found} found, but this app requires " + f"{required} or newer.", file=sys.stderr, ) raise SystemExit(1) def apply_style_manager() -> None: - """Hand color-scheme selection to libadwaita's system preference tracker.""" + """Hand color-scheme selection to libadwaita's preference tracker.""" Adw.StyleManager.get_default().set_color_scheme(Adw.ColorScheme.DEFAULT) Gtk.Window.set_default_icon_name(APP_ICON_NAME) def mount_status_line(mount: DisplayedMount) -> str: - """Build the AdwActionRow subtitle for a mount: `` · ``.""" + """Build the AdwActionRow subtitle: `` · ``.""" return f"{mount.mount_point} · {mount.status}" @@ -76,8 +77,8 @@ def run_gui() -> int: ensure_libadwaita_supported() if not Gtk.init_check(): print( - "GTK could not connect to your graphical session. Run this from your " - "desktop session, not a plain TTY.", + "GTK could not connect to your graphical session. Run this " + "from your desktop session, not a plain TTY.", file=sys.stderr, ) return 1 @@ -95,15 +96,19 @@ def build_shortcuts_dialog() -> Adw.ShortcutsDialog: dialog = Adw.ShortcutsDialog() general = Adw.ShortcutsSection(title="General") - general.add(Adw.ShortcutsItem(title="Add Share", action_name="win.add-share")) - general.add(Adw.ShortcutsItem(title="Refresh", action_name="win.refresh")) - general.add(Adw.ShortcutsItem(title="Primary Menu", action_name="win.show-menu")) + general.add(Adw.ShortcutsItem( + title="Add Share", action_name="win.add-share")) + general.add(Adw.ShortcutsItem( + title="Refresh", action_name="win.refresh")) + general.add(Adw.ShortcutsItem( + title="Primary Menu", action_name="win.show-menu")) general.add( Adw.ShortcutsItem( title="Keyboard Shortcuts", action_name="app.shortcuts" ) ) - general.add(Adw.ShortcutsItem(title="Close Window", action_name="win.close")) + general.add(Adw.ShortcutsItem( + title="Close Window", action_name="win.close")) general.add(Adw.ShortcutsItem(title="Quit", action_name="app.quit")) dialog.add(general) @@ -125,7 +130,8 @@ def __init__(self, main_window: "MainWindow") -> None: self.add_button = Gtk.Button(label="Add") self.add_button.add_css_class("suggested-action") self.add_button.set_sensitive(False) - self.add_button.connect("clicked", lambda _b: self._on_add_clicked()) + self.add_button.connect( + "clicked", lambda _b: self._on_add_clicked()) header = Adw.HeaderBar() header.pack_start(self.cancel_button) @@ -145,7 +151,8 @@ def __init__(self, main_window: "MainWindow") -> None: self.path_row.set_tooltip_text( "Example: //192.168.1.2/sharename or //hostname/sharename" ) - self.path_row.connect("changed", lambda _r: self._on_path_changed()) + self.path_row.connect( + "changed", lambda _r: self._on_path_changed()) share_group.add(self.path_row) self.host_spinner = Adw.Spinner() @@ -165,12 +172,14 @@ def __init__(self, main_window: "MainWindow") -> None: self.user_row = Adw.EntryRow() self.user_row.set_title("Username") - self.user_row.connect("changed", lambda _r: self._update_add_sensitive()) + self.user_row.connect( + "changed", lambda _r: self._update_add_sensitive()) self.credentials_group.add(self.user_row) self.password_row = Adw.PasswordEntryRow() self.password_row.set_title("Password") - self.password_row.connect("changed", lambda _r: self._update_add_sensitive()) + self.password_row.connect( + "changed", lambda _r: self._update_add_sensitive()) self.credentials_group.add(self.password_row) body = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=0) @@ -182,7 +191,7 @@ def __init__(self, main_window: "MainWindow") -> None: toolbar.set_content(body) self.set_child(toolbar) self.set_default_widget(self.add_button) - + self.connect("closed", self._cleanup) self.connect("map", lambda _d: self.path_row.grab_focus()) @@ -251,14 +260,16 @@ def _host_check_worker( try: share_path = check_smb_host_reachable(text) except MountManagerError as exc: - result: tuple[SharePath | None, BaseException | None] = (None, exc) + result: tuple[SharePath | None, + BaseException | None] = (None, exc) except Exception as exc: result = (None, exc) else: result = (share_path, None) if cancellable.is_cancelled(): return - GLib.idle_add(self._on_host_check_done, cancellable, result[0], result[1]) + GLib.idle_add(self._on_host_check_done, + cancellable, result[0], result[1]) def _on_host_check_done( self, @@ -266,14 +277,16 @@ def _on_host_check_done( share_path: SharePath | None, exc: BaseException | None, ) -> bool: - if cancellable.is_cancelled() or cancellable is not self._cancellable: + if (cancellable.is_cancelled() + or cancellable is not self._cancellable): return False # stale or cancelled; ignore self._cancellable = None if exc is not None: if isinstance(exc, MountManagerError): self._set_host_status(ok=False, message=str(exc)) else: - self._set_host_status(ok=False, message=f"Unexpected error: {exc}") + self._set_host_status( + ok=False, message=f"Unexpected error: {exc}") return False self.share_path = share_path self._set_host_status(ok=True, message="Host is reachable") @@ -316,7 +329,8 @@ def __init__(self, app: Adw.Application) -> None: self.set_icon_name(APP_ICON_NAME) about_action = Gio.SimpleAction.new("about", None) - about_action.connect("activate", lambda _a, _p: self.show_about_dialog()) + about_action.connect("activate", lambda _a, + _p: self.show_about_dialog()) self.add_action(about_action) close_action = Gio.SimpleAction.new("close", None) @@ -325,7 +339,8 @@ def __init__(self, app: Adw.Application) -> None: app.set_accels_for_action("win.close", ["w"]) add_share_action = Gio.SimpleAction.new("add-share", None) - add_share_action.connect("activate", lambda _a, _p: self.show_add_dialog()) + add_share_action.connect( + "activate", lambda _a, _p: self.show_add_dialog()) self.add_action(add_share_action) app.set_accels_for_action("win.add-share", ["n"]) @@ -335,7 +350,8 @@ def __init__(self, app: Adw.Application) -> None: app.set_accels_for_action("win.refresh", ["r"]) show_menu_action = Gio.SimpleAction.new("show-menu", None) - show_menu_action.connect("activate", lambda _a, _p: self._open_primary_menu()) + show_menu_action.connect( + "activate", lambda _a, _p: self._open_primary_menu()) self.add_action(show_menu_action) app.set_accels_for_action("win.show-menu", ["F10"]) @@ -347,7 +363,8 @@ def __init__(self, app: Adw.Application) -> None: self.menu_button.set_menu_model(menu) self.menu_button.set_tooltip_text("Primary menu") - refresh_button = Gtk.Button.new_from_icon_name("view-refresh-symbolic") + refresh_button = Gtk.Button.new_from_icon_name( + "view-refresh-symbolic") refresh_button.set_tooltip_text("Refresh") refresh_button.set_action_name("win.refresh") @@ -367,8 +384,9 @@ def __init__(self, app: Adw.Application) -> None: self.toast_overlay = Adw.ToastOverlay() - # Content area; Tasks 6-8 replace the list/empty children inside it. - self.content_box = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=0) + # Content area; Tasks 6-8 replace the list/empty children here. + self.content_box = Gtk.Box( + orientation=Gtk.Orientation.VERTICAL, spacing=0) self.toast_overlay.set_child(self.content_box) self.empty_page = Adw.StatusPage() @@ -440,7 +458,8 @@ def row_for(self, mount: DisplayedMount) -> Adw.ActionRow: mount_switch.set_active(mount.active) mount_switch.set_sensitive(not mount.needs_upgrade) if mount.needs_upgrade: - mount_switch.set_tooltip_text("Upgrade this older mount before enabling it") + mount_switch.set_tooltip_text( + "Upgrade this older mount before enabling it") else: mount_switch.set_tooltip_text( "Enable or disable on-demand access for this managed mount" @@ -455,13 +474,16 @@ def row_for(self, mount: DisplayedMount) -> Adw.ActionRow: upgrade_button = Gtk.Button(label="Upgrade") upgrade_button.set_valign(Gtk.Align.CENTER) upgrade_button.set_tooltip_text( - "Upgrade mount units using the existing encrypted credentials" + "Upgrade mount units using the existing encrypted " + "credentials" ) upgrade_button.add_css_class("suggested-action") - upgrade_button.connect("clicked", lambda _b: self.upgrade_mount(record)) + upgrade_button.connect( + "clicked", lambda _b: self.upgrade_mount(record)) row.add_suffix(upgrade_button) else: - open_button = Gtk.Button.new_from_icon_name("folder-open-symbolic") + open_button = Gtk.Button.new_from_icon_name( + "folder-open-symbolic") open_button.set_valign(Gtk.Align.CENTER) open_button.add_css_class("flat") open_button.set_sensitive(mount.openable) @@ -470,14 +492,16 @@ def row_for(self, mount: DisplayedMount) -> Adw.ActionRow: if mount.openable else "Enable on-demand access to open its folder" ) - open_button.connect("clicked", lambda _b: self.open_mount_folder(record)) + open_button.connect( + "clicked", lambda _b: self.open_mount_folder(record)) row.add_suffix(open_button) menu = Gio.Menu() menu.append("Delete\u2026", f"row.delete::{record.manager_id}") row_action_group = Gio.SimpleActionGroup() - delete_action = Gio.SimpleAction.new("delete", GLib_VariantType("s")) + delete_action = Gio.SimpleAction.new( + "delete", GLib_VariantType("s")) delete_action.connect( "activate", lambda _a, _p, r=record: self.confirm_delete(r) ) @@ -511,9 +535,11 @@ def show_about_dialog(self) -> None: def open_mount_folder(self, record: ManagedMount) -> None: if not record.mount_point.exists(): - self.show_toast(f"Mount folder does not exist: {record.mount_point}") + self.show_toast( + f"Mount folder does not exist: {record.mount_point}") return - launcher = Gtk.FileLauncher.new(Gio.File.new_for_path(str(record.mount_point))) + launcher = Gtk.FileLauncher.new( + Gio.File.new_for_path(str(record.mount_point))) launcher.launch(self, None, self._on_open_folder_done) def _on_open_folder_done( @@ -522,7 +548,8 @@ def _on_open_folder_done( try: launcher.launch_finish(result) except GLib.Error as exc: - if exc.matches(Gio.io_error_quark(), Gio.IOErrorEnum.CANCELLED): + if exc.matches( + Gio.io_error_quark(), Gio.IOErrorEnum.CANCELLED): return self.show_toast(f"Could not open folder: {exc.message}") @@ -538,7 +565,8 @@ def upgrade_mount(self, record: ManagedMount) -> None: self.refresh() self.show_toast(f"{record.source} upgraded") - def toggle_mount(self, record: ManagedMount, switch: Gtk.Switch) -> None: + def toggle_mount( + self, record: ManagedMount, switch: Gtk.Switch) -> None: enabled = switch.get_active() switch.set_sensitive(False) try: @@ -586,7 +614,10 @@ def _on_delete_response( class MountManagerApplication(Adw.Application): def __init__(self) -> None: - super().__init__(application_id=APP_ID, flags=Gio.ApplicationFlags.DEFAULT_FLAGS) + super().__init__( + application_id=APP_ID, + flags=Gio.ApplicationFlags.DEFAULT_FLAGS, + ) quit_action = Gio.SimpleAction.new("quit", None) quit_action.connect("activate", lambda _a, _p: self.quit()) @@ -594,7 +625,8 @@ def __init__(self) -> None: self.set_accels_for_action("app.quit", ["q"]) shortcuts_action = Gio.SimpleAction.new("shortcuts", None) - shortcuts_action.connect("activate", lambda _a, _p: self._show_shortcuts()) + shortcuts_action.connect( + "activate", lambda _a, _p: self._show_shortcuts()) self.add_action(shortcuts_action) self.set_accels_for_action("app.shortcuts", ["question"]) diff --git a/tests/test_libadwaita_support.py b/tests/test_libadwaita_support.py index b18608e..3fd194c 100644 --- a/tests/test_libadwaita_support.py +++ b/tests/test_libadwaita_support.py @@ -2,24 +2,24 @@ import unittest -from mount_manager import _libadwaita_supports +from mount_manager import libadwaita_supports class LibadwaitaSupportsTest(unittest.TestCase): def test_minimum_supported_version(self) -> None: - self.assertTrue(_libadwaita_supports(1, 8)) + self.assertTrue(libadwaita_supports(1, 8)) def test_newer_minor_supported(self) -> None: - self.assertTrue(_libadwaita_supports(1, 9)) + self.assertTrue(libadwaita_supports(1, 9)) def test_newer_major_supported(self) -> None: - self.assertTrue(_libadwaita_supports(2, 0)) + self.assertTrue(libadwaita_supports(2, 0)) def test_older_minor_unsupported(self) -> None: - self.assertFalse(_libadwaita_supports(1, 7)) + self.assertFalse(libadwaita_supports(1, 7)) def test_older_major_unsupported(self) -> None: - self.assertFalse(_libadwaita_supports(0, 99)) + self.assertFalse(libadwaita_supports(0, 99)) if __name__ == "__main__": From 570eada2adddf8369585f90f55b70560e22ffc77 Mon Sep 17 00:00:00 2001 From: meowtypes Date: Sat, 30 May 2026 07:18:31 -0700 Subject: [PATCH 38/41] fmt: more ruff fmt formatting --- mount_manager_ui.py | 123 +++++++++++++++++--------------------------- 1 file changed, 48 insertions(+), 75 deletions(-) diff --git a/mount_manager_ui.py b/mount_manager_ui.py index 6ce5581..3107f5a 100644 --- a/mount_manager_ui.py +++ b/mount_manager_ui.py @@ -5,12 +5,6 @@ GTK when invoked with ``--helper``. """ -import sys -import threading -import gi -gi.require_version("Adw", "1") -gi.require_version("Gdk", "4.0") -gi.require_version("Gtk", "4.0") from mount_manager import ( APP_DEVELOPERS, APP_ICON_NAME, @@ -31,13 +25,15 @@ request_helper_upgrade, validate_credentials, ) -from gi.repository import ( - Adw, - Gdk, - Gio, - GLib, - Gtk -) + +import sys +import threading +import gi + +gi.require_version("Adw", "1") +gi.require_version("Gdk", "4.0") +gi.require_version("Gtk", "4.0") +from gi.repository import Adw, Gdk, Gio, GLib, Gtk def GLib_markup_escape(text: str) -> str: @@ -55,8 +51,7 @@ def ensure_libadwaita_supported() -> None: required = ".".join(str(v) for v in MIN_LIBADWAITA_VERSION) found = f"{Adw.MAJOR_VERSION}.{Adw.MINOR_VERSION}" print( - f"libadwaita {found} found, but this app requires " - f"{required} or newer.", + f"libadwaita {found} found, but this app requires {required} or newer.", file=sys.stderr, ) raise SystemExit(1) @@ -96,19 +91,15 @@ def build_shortcuts_dialog() -> Adw.ShortcutsDialog: dialog = Adw.ShortcutsDialog() general = Adw.ShortcutsSection(title="General") - general.add(Adw.ShortcutsItem( - title="Add Share", action_name="win.add-share")) - general.add(Adw.ShortcutsItem( - title="Refresh", action_name="win.refresh")) - general.add(Adw.ShortcutsItem( - title="Primary Menu", action_name="win.show-menu")) + general.add(Adw.ShortcutsItem(title="Add Share", action_name="win.add-share")) + general.add(Adw.ShortcutsItem(title="Refresh", action_name="win.refresh")) general.add( - Adw.ShortcutsItem( - title="Keyboard Shortcuts", action_name="app.shortcuts" - ) + Adw.ShortcutsItem(title="Primary Menu", action_name="win.show-menu") ) - general.add(Adw.ShortcutsItem( - title="Close Window", action_name="win.close")) + general.add( + Adw.ShortcutsItem(title="Keyboard Shortcuts", action_name="app.shortcuts") + ) + general.add(Adw.ShortcutsItem(title="Close Window", action_name="win.close")) general.add(Adw.ShortcutsItem(title="Quit", action_name="app.quit")) dialog.add(general) @@ -130,8 +121,7 @@ def __init__(self, main_window: "MainWindow") -> None: self.add_button = Gtk.Button(label="Add") self.add_button.add_css_class("suggested-action") self.add_button.set_sensitive(False) - self.add_button.connect( - "clicked", lambda _b: self._on_add_clicked()) + self.add_button.connect("clicked", lambda _b: self._on_add_clicked()) header = Adw.HeaderBar() header.pack_start(self.cancel_button) @@ -151,8 +141,7 @@ def __init__(self, main_window: "MainWindow") -> None: self.path_row.set_tooltip_text( "Example: //192.168.1.2/sharename or //hostname/sharename" ) - self.path_row.connect( - "changed", lambda _r: self._on_path_changed()) + self.path_row.connect("changed", lambda _r: self._on_path_changed()) share_group.add(self.path_row) self.host_spinner = Adw.Spinner() @@ -172,14 +161,14 @@ def __init__(self, main_window: "MainWindow") -> None: self.user_row = Adw.EntryRow() self.user_row.set_title("Username") - self.user_row.connect( - "changed", lambda _r: self._update_add_sensitive()) + self.user_row.connect("changed", lambda _r: self._update_add_sensitive()) self.credentials_group.add(self.user_row) self.password_row = Adw.PasswordEntryRow() self.password_row.set_title("Password") self.password_row.connect( - "changed", lambda _r: self._update_add_sensitive()) + "changed", lambda _r: self._update_add_sensitive() + ) self.credentials_group.add(self.password_row) body = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=0) @@ -254,22 +243,18 @@ def _run_host_check(self) -> bool: thread.start() return False # don't repeat the timeout - def _host_check_worker( - self, cancellable: Gio.Cancellable, text: str - ) -> None: + def _host_check_worker(self, cancellable: Gio.Cancellable, text: str) -> None: try: share_path = check_smb_host_reachable(text) except MountManagerError as exc: - result: tuple[SharePath | None, - BaseException | None] = (None, exc) + result: tuple[SharePath | None, BaseException | None] = (None, exc) except Exception as exc: result = (None, exc) else: result = (share_path, None) if cancellable.is_cancelled(): return - GLib.idle_add(self._on_host_check_done, - cancellable, result[0], result[1]) + GLib.idle_add(self._on_host_check_done, cancellable, result[0], result[1]) def _on_host_check_done( self, @@ -277,16 +262,14 @@ def _on_host_check_done( share_path: SharePath | None, exc: BaseException | None, ) -> bool: - if (cancellable.is_cancelled() - or cancellable is not self._cancellable): + if cancellable.is_cancelled() or cancellable is not self._cancellable: return False # stale or cancelled; ignore self._cancellable = None if exc is not None: if isinstance(exc, MountManagerError): self._set_host_status(ok=False, message=str(exc)) else: - self._set_host_status( - ok=False, message=f"Unexpected error: {exc}") + self._set_host_status(ok=False, message=f"Unexpected error: {exc}") return False self.share_path = share_path self._set_host_status(ok=True, message="Host is reachable") @@ -329,8 +312,7 @@ def __init__(self, app: Adw.Application) -> None: self.set_icon_name(APP_ICON_NAME) about_action = Gio.SimpleAction.new("about", None) - about_action.connect("activate", lambda _a, - _p: self.show_about_dialog()) + about_action.connect("activate", lambda _a, _p: self.show_about_dialog()) self.add_action(about_action) close_action = Gio.SimpleAction.new("close", None) @@ -339,8 +321,7 @@ def __init__(self, app: Adw.Application) -> None: app.set_accels_for_action("win.close", ["w"]) add_share_action = Gio.SimpleAction.new("add-share", None) - add_share_action.connect( - "activate", lambda _a, _p: self.show_add_dialog()) + add_share_action.connect("activate", lambda _a, _p: self.show_add_dialog()) self.add_action(add_share_action) app.set_accels_for_action("win.add-share", ["n"]) @@ -351,7 +332,8 @@ def __init__(self, app: Adw.Application) -> None: show_menu_action = Gio.SimpleAction.new("show-menu", None) show_menu_action.connect( - "activate", lambda _a, _p: self._open_primary_menu()) + "activate", lambda _a, _p: self._open_primary_menu() + ) self.add_action(show_menu_action) app.set_accels_for_action("win.show-menu", ["F10"]) @@ -363,8 +345,7 @@ def __init__(self, app: Adw.Application) -> None: self.menu_button.set_menu_model(menu) self.menu_button.set_tooltip_text("Primary menu") - refresh_button = Gtk.Button.new_from_icon_name( - "view-refresh-symbolic") + refresh_button = Gtk.Button.new_from_icon_name("view-refresh-symbolic") refresh_button.set_tooltip_text("Refresh") refresh_button.set_action_name("win.refresh") @@ -385,8 +366,7 @@ def __init__(self, app: Adw.Application) -> None: self.toast_overlay = Adw.ToastOverlay() # Content area; Tasks 6-8 replace the list/empty children here. - self.content_box = Gtk.Box( - orientation=Gtk.Orientation.VERTICAL, spacing=0) + self.content_box = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=0) self.toast_overlay.set_child(self.content_box) self.empty_page = Adw.StatusPage() @@ -459,7 +439,8 @@ def row_for(self, mount: DisplayedMount) -> Adw.ActionRow: mount_switch.set_sensitive(not mount.needs_upgrade) if mount.needs_upgrade: mount_switch.set_tooltip_text( - "Upgrade this older mount before enabling it") + "Upgrade this older mount before enabling it" + ) else: mount_switch.set_tooltip_text( "Enable or disable on-demand access for this managed mount" @@ -474,16 +455,13 @@ def row_for(self, mount: DisplayedMount) -> Adw.ActionRow: upgrade_button = Gtk.Button(label="Upgrade") upgrade_button.set_valign(Gtk.Align.CENTER) upgrade_button.set_tooltip_text( - "Upgrade mount units using the existing encrypted " - "credentials" + "Upgrade mount units using the existing encrypted credentials" ) upgrade_button.add_css_class("suggested-action") - upgrade_button.connect( - "clicked", lambda _b: self.upgrade_mount(record)) + upgrade_button.connect("clicked", lambda _b: self.upgrade_mount(record)) row.add_suffix(upgrade_button) else: - open_button = Gtk.Button.new_from_icon_name( - "folder-open-symbolic") + open_button = Gtk.Button.new_from_icon_name("folder-open-symbolic") open_button.set_valign(Gtk.Align.CENTER) open_button.add_css_class("flat") open_button.set_sensitive(mount.openable) @@ -493,15 +471,15 @@ def row_for(self, mount: DisplayedMount) -> Adw.ActionRow: else "Enable on-demand access to open its folder" ) open_button.connect( - "clicked", lambda _b: self.open_mount_folder(record)) + "clicked", lambda _b: self.open_mount_folder(record) + ) row.add_suffix(open_button) menu = Gio.Menu() menu.append("Delete\u2026", f"row.delete::{record.manager_id}") row_action_group = Gio.SimpleActionGroup() - delete_action = Gio.SimpleAction.new( - "delete", GLib_VariantType("s")) + delete_action = Gio.SimpleAction.new("delete", GLib_VariantType("s")) delete_action.connect( "activate", lambda _a, _p, r=record: self.confirm_delete(r) ) @@ -535,11 +513,11 @@ def show_about_dialog(self) -> None: def open_mount_folder(self, record: ManagedMount) -> None: if not record.mount_point.exists(): - self.show_toast( - f"Mount folder does not exist: {record.mount_point}") + self.show_toast(f"Mount folder does not exist: {record.mount_point}") return launcher = Gtk.FileLauncher.new( - Gio.File.new_for_path(str(record.mount_point))) + Gio.File.new_for_path(str(record.mount_point)) + ) launcher.launch(self, None, self._on_open_folder_done) def _on_open_folder_done( @@ -548,8 +526,7 @@ def _on_open_folder_done( try: launcher.launch_finish(result) except GLib.Error as exc: - if exc.matches( - Gio.io_error_quark(), Gio.IOErrorEnum.CANCELLED): + if exc.matches(Gio.io_error_quark(), Gio.IOErrorEnum.CANCELLED): return self.show_toast(f"Could not open folder: {exc.message}") @@ -565,8 +542,7 @@ def upgrade_mount(self, record: ManagedMount) -> None: self.refresh() self.show_toast(f"{record.source} upgraded") - def toggle_mount( - self, record: ManagedMount, switch: Gtk.Switch) -> None: + def toggle_mount(self, record: ManagedMount, switch: Gtk.Switch) -> None: enabled = switch.get_active() switch.set_sensitive(False) try: @@ -588,9 +564,7 @@ def confirm_delete(self, record: ManagedMount) -> None: ) alert.add_response("cancel", "Cancel") alert.add_response("delete", "Delete Share") - alert.set_response_appearance( - "delete", Adw.ResponseAppearance.DESTRUCTIVE - ) + alert.set_response_appearance("delete", Adw.ResponseAppearance.DESTRUCTIVE) alert.set_default_response("cancel") alert.set_close_response("cancel") alert.connect("response", self._on_delete_response, record) @@ -625,8 +599,7 @@ def __init__(self) -> None: self.set_accels_for_action("app.quit", ["q"]) shortcuts_action = Gio.SimpleAction.new("shortcuts", None) - shortcuts_action.connect( - "activate", lambda _a, _p: self._show_shortcuts()) + shortcuts_action.connect("activate", lambda _a, _p: self._show_shortcuts()) self.add_action(shortcuts_action) self.set_accels_for_action("app.shortcuts", ["question"]) From 1216123c3c86c0b16294d7e416ee812ae7a298b0 Mon Sep 17 00:00:00 2001 From: meowtypes Date: Sun, 7 Jun 2026 07:03:31 -0700 Subject: [PATCH 39/41] bump release version --- data/metainfo/io.github.xarishark.mount-manager.metainfo.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/data/metainfo/io.github.xarishark.mount-manager.metainfo.xml b/data/metainfo/io.github.xarishark.mount-manager.metainfo.xml index 83137e1..9b5933a 100644 --- a/data/metainfo/io.github.xarishark.mount-manager.metainfo.xml +++ b/data/metainfo/io.github.xarishark.mount-manager.metainfo.xml @@ -30,7 +30,7 @@ - + From 785ea4b8845d85fcea1c105863937edddbb96360 Mon Sep 17 00:00:00 2001 From: meowtypes Date: Sun, 7 Jun 2026 13:47:21 -0700 Subject: [PATCH 40/41] refactor(ui): polish Add Share dialog and simplify mount_manager_ui code UX fixes for the Add SMB Share dialog: - Show example syntax as the Share group's description so users see "//hostname/sharename" before typing. - Hide the credentials group until the host check succeeds, instead of just disabling it, so the form clearly progresses. - Replace Adw.PreferencesPage with Adw.Clamp + Gtk.Box so the dialog grows to fit revealed content instead of pinning a fixed height behind a scrollbar. - Drop the redundant header-bar close button; Cancel + Esc remain. - Use canonical Adwaita icon names (object-select-symbolic, dialog-error-symbolic) for the host-check status indicator. Main window polish: - Make the Add Share header button icon-only per GNOME HIG. - Drop the redundant empty-state description. Refactor mount_manager_ui.py (no behavior change): - Add a bind_action helper to collapse repeated SimpleAction wiring. - Extract _cancel_pending_host_check and _run_helper_action helpers. - Inline the GLib_VariantType wrapper, table-drive the shortcuts items, simplify the host-check worker and row-clearing loop. Docs: - Update AGENTS.md and the libadwaita migration design spec to reflect the Clamp + Box body and the visible (rather than sensitive) credentials-group reveal. 623 -> 603 lines in mount_manager_ui.py. All tests still pass. --- AGENTS.md | 5 +- .../2026-05-28-libadwaita-migration-design.md | 12 +- mount_manager_ui.py | 207 ++++++++---------- 3 files changed, 106 insertions(+), 118 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index afa4793..db1af6b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -40,7 +40,10 @@ The application is split across two files: - The Add Share flow is a single-page progressive-reveal `Adw.Dialog` with a 300ms debounced host check (`GLib.timeout_add` + `GLib.source_remove`). Any pending timer **must** be cancelled on the dialog's `"closed"` signal to avoid firing callbacks on - destroyed widgets. + destroyed widgets. The dialog body is an `Adw.Clamp` wrapping a vertical `Gtk.Box` + of `Adw.PreferencesGroup`s — **not** `Adw.PreferencesPage`, whose internal + `ScrolledWindow` would fix the dialog height and hide content revealed at runtime + (e.g. the credentials group) behind a scrollbar. - Always escape user-controlled strings (mount paths, statuses) with `GLib.markup_escape_text` before passing them to widgets that render Pango markup. - About box uses `Adw.AboutDialog`. diff --git a/docs/specs/2026-05-28-libadwaita-migration-design.md b/docs/specs/2026-05-28-libadwaita-migration-design.md index 2fc61ff..000d86b 100644 --- a/docs/specs/2026-05-28-libadwaita-migration-design.md +++ b/docs/specs/2026-05-28-libadwaita-migration-design.md @@ -115,11 +115,13 @@ hidden and replaced by an `Adw.StatusPage`: - Header: `Adw.HeaderBar` with `Cancel` (start) and a suggested-action `Add` (end). `Add` is insensitive until the host check has succeeded and both credential fields are non-empty. -- Body: `Adw.Clamp` → `Adw.PreferencesPage` with two - `Adw.PreferencesGroup`s: +- Body: `Adw.Clamp` wrapping a vertical `Gtk.Box` of two + `Adw.PreferencesGroup`s (not `Adw.PreferencesPage`, whose internal + `ScrolledWindow` would pin the dialog at a fixed height and prevent it from + growing when the credentials group is revealed): - **Share** group: - - `Adw.EntryRow` titled "Share path". Placeholder example: - `//192.168.1.2/sharename or //hostname/sharename`. + - `Adw.EntryRow` titled "Share path". The group description carries the + example: `//192.168.1.2/sharename or //hostname/sharename`. - The host check (currently a separate "Check host" button) runs automatically after a short typing debounce once the entered path parses. A spinner is shown in the row's apply / trailing area while the @@ -128,7 +130,7 @@ hidden and replaced by an `Adw.StatusPage`: - **Credentials** group: - `Adw.EntryRow` titled "Username". - `Adw.PasswordEntryRow` titled "Password". - - The group's `sensitive` property is bound to "host check succeeded". + - The group's `visible` property is bound to "host check succeeded". - Submitting `Add` runs the existing test-mount → helper-create flow on a worker thread (today's logic is preserved). On success the dialog closes, the main window's list refreshes, and a toast is shown. On failure an diff --git a/mount_manager_ui.py b/mount_manager_ui.py index 3107f5a..22c60be 100644 --- a/mount_manager_ui.py +++ b/mount_manager_ui.py @@ -41,10 +41,6 @@ def GLib_markup_escape(text: str) -> str: return GLib.markup_escape_text(text, -1) -def GLib_VariantType(spec: str) -> GLib.VariantType: - return GLib.VariantType.new(spec) - - def ensure_libadwaita_supported() -> None: """Print an error and raise SystemExit if libadwaita is too old.""" if not libadwaita_supports(Adw.MAJOR_VERSION, Adw.MINOR_VERSION): @@ -86,21 +82,37 @@ def run_gui() -> int: return 1 apply_style_manager() + def bind_action( + owner, + app, + qualified_name: str, + callback, + accels: tuple[str, ...] = (), + ) -> None: + """Register a parameterless action on ``owner`` and wire its accelerators on ``app``. + + ``qualified_name`` is the full action name (``"win.refresh"`` / ``"app.quit"``). + """ + action = Gio.SimpleAction.new(qualified_name.split(".", 1)[1], None) + action.connect("activate", lambda _a, _p: callback()) + owner.add_action(action) + if accels: + app.set_accels_for_action(qualified_name, list(accels)) + def build_shortcuts_dialog() -> Adw.ShortcutsDialog: """Construct the keyboard shortcuts dialog for the app.""" dialog = Adw.ShortcutsDialog() general = Adw.ShortcutsSection(title="General") - general.add(Adw.ShortcutsItem(title="Add Share", action_name="win.add-share")) - general.add(Adw.ShortcutsItem(title="Refresh", action_name="win.refresh")) - general.add( - Adw.ShortcutsItem(title="Primary Menu", action_name="win.show-menu") - ) - general.add( - Adw.ShortcutsItem(title="Keyboard Shortcuts", action_name="app.shortcuts") - ) - general.add(Adw.ShortcutsItem(title="Close Window", action_name="win.close")) - general.add(Adw.ShortcutsItem(title="Quit", action_name="app.quit")) + for title, action_name in ( + ("Add Share", "win.add-share"), + ("Refresh", "win.refresh"), + ("Primary Menu", "win.show-menu"), + ("Keyboard Shortcuts", "app.shortcuts"), + ("Close Window", "win.close"), + ("Quit", "app.quit"), + ): + general.add(Adw.ShortcutsItem(title=title, action_name=action_name)) dialog.add(general) return dialog @@ -124,23 +136,28 @@ def __init__(self, main_window: "MainWindow") -> None: self.add_button.connect("clicked", lambda _b: self._on_add_clicked()) header = Adw.HeaderBar() + header.set_show_end_title_buttons(False) header.pack_start(self.cancel_button) header.pack_end(self.add_button) self.banner = Adw.Banner() self.banner.set_revealed(False) - page = Adw.PreferencesPage() + groups_box = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=24) + groups_box.set_margin_top(24) + groups_box.set_margin_bottom(24) + groups_box.set_margin_start(12) + groups_box.set_margin_end(12) share_group = Adw.PreferencesGroup() share_group.set_title("Share") - page.add(share_group) + share_group.set_description( + "Example: //192.168.1.2/sharename or //hostname/sharename" + ) + groups_box.append(share_group) self.path_row = Adw.EntryRow() self.path_row.set_title("Share path") - self.path_row.set_tooltip_text( - "Example: //192.168.1.2/sharename or //hostname/sharename" - ) self.path_row.connect("changed", lambda _r: self._on_path_changed()) share_group.add(self.path_row) @@ -156,8 +173,8 @@ def __init__(self, main_window: "MainWindow") -> None: self.credentials_group = Adw.PreferencesGroup() self.credentials_group.set_title("Credentials") - self.credentials_group.set_sensitive(False) - page.add(self.credentials_group) + self.credentials_group.set_visible(False) + groups_box.append(self.credentials_group) self.user_row = Adw.EntryRow() self.user_row.set_title("Username") @@ -171,9 +188,13 @@ def __init__(self, main_window: "MainWindow") -> None: ) self.credentials_group.add(self.password_row) + clamp = Adw.Clamp() + clamp.set_maximum_size(600) + clamp.set_child(groups_box) + body = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=0) body.append(self.banner) - body.append(page) + body.append(clamp) toolbar = Adw.ToolbarView() toolbar.add_top_bar(header) @@ -184,7 +205,7 @@ def __init__(self, main_window: "MainWindow") -> None: self.connect("closed", self._cleanup) self.connect("map", lambda _d: self.path_row.grab_focus()) - def _cleanup(self, *_args) -> None: + def _cancel_pending_host_check(self) -> None: if self._cancellable is not None: self._cancellable.cancel() self._cancellable = None @@ -192,6 +213,9 @@ def _cleanup(self, *_args) -> None: GLib.source_remove(self._debounce_id) self._debounce_id = 0 + def _cleanup(self, *_args) -> None: + self._cancel_pending_host_check() + def _show_banner(self, message: str) -> None: self.banner.set_title(message) self.banner.set_revealed(True) @@ -206,24 +230,19 @@ def _set_host_status(self, *, ok: bool | None, message: str) -> None: self.path_row.set_title("Share path") return if ok: - self.host_status_icon.set_from_icon_name("checkmark-symbolic") + self.host_status_icon.set_from_icon_name("object-select-symbolic") else: - self.host_status_icon.set_from_icon_name("error-symbolic") + self.host_status_icon.set_from_icon_name("dialog-error-symbolic") self.host_status_icon.set_visible(True) self.host_status_icon.set_tooltip_text(message) def _on_path_changed(self) -> None: self.share_path = None - self.credentials_group.set_sensitive(False) + self.credentials_group.set_visible(False) self._update_add_sensitive() self._hide_banner() self._set_host_status(ok=None, message="") - if self._cancellable is not None: - self._cancellable.cancel() - self._cancellable = None - if self._debounce_id: - GLib.source_remove(self._debounce_id) - self._debounce_id = 0 + self._cancel_pending_host_check() text = self.path_row.get_text().strip() if not text: return @@ -245,13 +264,12 @@ def _run_host_check(self) -> bool: def _host_check_worker(self, cancellable: Gio.Cancellable, text: str) -> None: try: - share_path = check_smb_host_reachable(text) - except MountManagerError as exc: - result: tuple[SharePath | None, BaseException | None] = (None, exc) + result: tuple[SharePath | None, BaseException | None] = ( + check_smb_host_reachable(text), + None, + ) except Exception as exc: result = (None, exc) - else: - result = (share_path, None) if cancellable.is_cancelled(): return GLib.idle_add(self._on_host_check_done, cancellable, result[0], result[1]) @@ -273,7 +291,7 @@ def _on_host_check_done( return False self.share_path = share_path self._set_host_status(ok=True, message="Host is reachable") - self.credentials_group.set_sensitive(True) + self.credentials_group.set_visible(True) self._update_add_sensitive() return False @@ -311,31 +329,11 @@ def __init__(self, app: Adw.Application) -> None: self.set_default_size(760, 480) self.set_icon_name(APP_ICON_NAME) - about_action = Gio.SimpleAction.new("about", None) - about_action.connect("activate", lambda _a, _p: self.show_about_dialog()) - self.add_action(about_action) - - close_action = Gio.SimpleAction.new("close", None) - close_action.connect("activate", lambda _a, _p: self.close()) - self.add_action(close_action) - app.set_accels_for_action("win.close", ["w"]) - - add_share_action = Gio.SimpleAction.new("add-share", None) - add_share_action.connect("activate", lambda _a, _p: self.show_add_dialog()) - self.add_action(add_share_action) - app.set_accels_for_action("win.add-share", ["n"]) - - refresh_action = Gio.SimpleAction.new("refresh", None) - refresh_action.connect("activate", lambda _a, _p: self.refresh()) - self.add_action(refresh_action) - app.set_accels_for_action("win.refresh", ["r"]) - - show_menu_action = Gio.SimpleAction.new("show-menu", None) - show_menu_action.connect( - "activate", lambda _a, _p: self._open_primary_menu() - ) - self.add_action(show_menu_action) - app.set_accels_for_action("win.show-menu", ["F10"]) + bind_action(self, app, "win.about", self.show_about_dialog) + bind_action(self, app, "win.close", self.close, ("w",)) + bind_action(self, app, "win.add-share", self.show_add_dialog, ("n",)) + bind_action(self, app, "win.refresh", self.refresh, ("r",)) + bind_action(self, app, "win.show-menu", self._open_primary_menu, ("F10",)) menu = Gio.Menu() menu.append("Keyboard Shortcuts", "app.shortcuts") @@ -349,13 +347,8 @@ def __init__(self, app: Adw.Application) -> None: refresh_button.set_tooltip_text("Refresh") refresh_button.set_action_name("win.refresh") - add_button_content = Adw.ButtonContent( - icon_name="list-add-symbolic", - label="Add Share", - ) - add_button = Gtk.Button() - add_button.set_child(add_button_content) - add_button.set_tooltip_text("Mount a new SMB share") + add_button = Gtk.Button.new_from_icon_name("list-add-symbolic") + add_button.set_tooltip_text("Add SMB share") add_button.set_action_name("win.add-share") header = Adw.HeaderBar() @@ -372,7 +365,6 @@ def __init__(self, app: Adw.Application) -> None: self.empty_page = Adw.StatusPage() self.empty_page.set_icon_name("network-server-symbolic") self.empty_page.set_title("No SMB shares") - self.empty_page.set_description('Click "Add Share" to mount one') self.empty_page.set_vexpand(True) empty_action = Gtk.Button(label="Add Share") @@ -406,10 +398,7 @@ def show_toast(self, message: str) -> None: self.toast_overlay.add_toast(Adw.Toast(title=message)) def refresh(self) -> None: - while True: - row = self.mount_group.get_row(0) - if row is None: - break + while (row := self.mount_group.get_row(0)) is not None: self.mount_group.remove(row) mounts = load_displayed_mounts() @@ -479,7 +468,7 @@ def row_for(self, mount: DisplayedMount) -> Adw.ActionRow: menu.append("Delete\u2026", f"row.delete::{record.manager_id}") row_action_group = Gio.SimpleActionGroup() - delete_action = Gio.SimpleAction.new("delete", GLib_VariantType("s")) + delete_action = Gio.SimpleAction.new("delete", GLib.VariantType.new("s")) delete_action.connect( "activate", lambda _a, _p, r=record: self.confirm_delete(r) ) @@ -530,29 +519,29 @@ def _on_open_folder_done( return self.show_toast(f"Could not open folder: {exc.message}") - def upgrade_mount(self, record: ManagedMount) -> None: + def _run_helper_action(self, label: str, callback) -> bool: + """Invoke a privileged helper callback, toast on failure, return True on success.""" try: - request_helper_upgrade(record) - except MountManagerError as exc: - self.show_toast(f"Upgrade failed: {exc}") - return + callback() except Exception as exc: - self.show_toast(f"Upgrade failed: {exc}") - return - self.refresh() - self.show_toast(f"{record.source} upgraded") + self.show_toast(f"{label} failed: {exc}") + return False + return True + + def upgrade_mount(self, record: ManagedMount) -> None: + if self._run_helper_action( + "Upgrade", lambda: request_helper_upgrade(record) + ): + self.refresh() + self.show_toast(f"{record.source} upgraded") def toggle_mount(self, record: ManagedMount, switch: Gtk.Switch) -> None: enabled = switch.get_active() switch.set_sensitive(False) - try: - request_helper_set_enabled(record, enabled) - except MountManagerError as exc: - self.show_toast(f"Toggle failed: {exc}") - except Exception as exc: - self.show_toast(f"Toggle failed: {exc}") - finally: - self.refresh() + self._run_helper_action( + "Toggle", lambda: request_helper_set_enabled(record, enabled) + ) + self.refresh() def confirm_delete(self, record: ManagedMount) -> None: alert = Adw.AlertDialog( @@ -575,16 +564,11 @@ def _on_delete_response( ) -> None: if response != "delete": return - try: - request_helper_delete(record) - except MountManagerError as exc: - self.show_toast(f"Delete failed: {exc}") - return - except Exception as exc: - self.show_toast(f"Delete failed: {exc}") - return - self.refresh() - self.show_toast(f"{record.source} removed") + if self._run_helper_action( + "Delete", lambda: request_helper_delete(record) + ): + self.refresh() + self.show_toast(f"{record.source} removed") class MountManagerApplication(Adw.Application): def __init__(self) -> None: @@ -593,15 +577,14 @@ def __init__(self) -> None: flags=Gio.ApplicationFlags.DEFAULT_FLAGS, ) - quit_action = Gio.SimpleAction.new("quit", None) - quit_action.connect("activate", lambda _a, _p: self.quit()) - self.add_action(quit_action) - self.set_accels_for_action("app.quit", ["q"]) - - shortcuts_action = Gio.SimpleAction.new("shortcuts", None) - shortcuts_action.connect("activate", lambda _a, _p: self._show_shortcuts()) - self.add_action(shortcuts_action) - self.set_accels_for_action("app.shortcuts", ["question"]) + bind_action(self, self, "app.quit", self.quit, ("q",)) + bind_action( + self, + self, + "app.shortcuts", + self._show_shortcuts, + ("question",), + ) def _show_shortcuts(self) -> None: window = self.props.active_window From 163c79f0fd7fffe540c1c509ecf20e21457917ff Mon Sep 17 00:00:00 2001 From: meowtypes Date: Sun, 7 Jun 2026 14:29:03 -0700 Subject: [PATCH 41/41] cleanup comments --- mount_manager_ui.py | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/mount_manager_ui.py b/mount_manager_ui.py index 22c60be..e0d7eba 100644 --- a/mount_manager_ui.py +++ b/mount_manager_ui.py @@ -260,7 +260,7 @@ def _run_host_check(self) -> bool: daemon=True, ) thread.start() - return False # don't repeat the timeout + return False def _host_check_worker(self, cancellable: Gio.Cancellable, text: str) -> None: try: @@ -358,7 +358,6 @@ def __init__(self, app: Adw.Application) -> None: self.toast_overlay = Adw.ToastOverlay() - # Content area; Tasks 6-8 replace the list/empty children here. self.content_box = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=0) self.toast_overlay.set_child(self.content_box)