Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
41 commits
Select commit Hold shift + click to select a range
88e9da8
docs: add libadwaita migration spec and implementation plan
meowtypes May 28, 2026
dd15f3c
test: add unittest scaffolding with import smoke test
meowtypes May 28, 2026
9c207e1
feat: add libadwaita version comparator
meowtypes May 28, 2026
b7aa443
refactor: split GUI code into mount_manager_ui module
meowtypes May 28, 2026
fe9a861
feat(ui): switch to Adw.Application and Adw.StyleManager
meowtypes May 28, 2026
2100d02
feat(ui): adopt Adw.ApplicationWindow with ToolbarView and ToastOverlay
meowtypes May 28, 2026
342285d
feat(ui): add mount_status_line helper
meowtypes May 28, 2026
9e1f242
feat(ui): render mounts as AdwPreferencesGroup with AdwActionRow
meowtypes May 28, 2026
937c83e
fix(ui): correctly clear AdwActionRow children on refresh
meowtypes May 28, 2026
30548eb
feat(ui): replace empty label with Adw.StatusPage
meowtypes May 28, 2026
cd458dc
feat(ui): replace AddShareWindow with AdwDialog and progressive reveal
meowtypes May 28, 2026
8fb7724
fix(ui): cancel AddShareDialog debounce timer on close
meowtypes May 28, 2026
e090f9b
feat(ui): replace DeleteMountWindow with Adw.AlertDialog
meowtypes May 28, 2026
74fed38
feat(ui): replace MessageWindow with AdwToast notifications
meowtypes May 28, 2026
8a6ed27
feat(ui): use Adw.AboutDialog
meowtypes May 28, 2026
da0dd32
build: include mount_manager_ui in packaging and document libadwaita …
meowtypes May 28, 2026
7c1d568
chore: remove dead code after libadwaita migration
meowtypes May 28, 2026
c01dfff
docs: add agent guidance for architecture, UI conventions, and packaging
meowtypes May 28, 2026
988f7db
fix(ui): run AddShareDialog host check off the main thread
meowtypes May 28, 2026
8edcbfc
fix(ui): correct post-create toast wording
meowtypes May 28, 2026
4e2882b
fix(ui): correct post-upgrade toast wording
meowtypes May 28, 2026
aad8e4b
fix(ui): align UI copy with GNOME HIG (toasts, tooltips, labels)
meowtypes May 28, 2026
1dc470f
refactor(ui): use modern symbolic icon names
meowtypes May 28, 2026
6cf7385
fix(ui): improve AddShareDialog focus and keyboard submit
meowtypes May 28, 2026
0abfaa4
refactor(ui): drop duplicate developer field in About dialog
meowtypes May 28, 2026
e116d3a
fix(ui): restyle header-bar Add Share button to follow HIG
meowtypes May 28, 2026
9097b9d
feat(ui): add keyboard shortcuts and shortcuts window
meowtypes May 28, 2026
3106ecb
feat: raise minimum libadwaita to 1.8
meowtypes May 28, 2026
da80bf5
refactor(ui): use Adw.Spinner in Add Share dialog
meowtypes May 28, 2026
2a5a17c
refactor(ui): use Adw.ShortcutsDialog for keyboard shortcuts
meowtypes May 28, 2026
b2e1fb3
refactor(ui): open mount folders with Gtk.FileLauncher
meowtypes May 28, 2026
1ab82fa
feat(ui): render mount rows as separate cards
meowtypes May 28, 2026
ff0f05f
docs: add HIG audit and libadwaita 1.8 bump specs and plans
meowtypes May 28, 2026
e599875
docs: move plans/ and specs/ up one directory level
meowtypes May 28, 2026
2f0c9bc
build: re-anchor appimage-helper.patch after refactors
meowtypes May 28, 2026
6f7a002
fix(packaging): install mount_manager.py under its real name
meowtypes May 28, 2026
15ac05a
fmt: pep8 fmt sweep
meowtypes May 30, 2026
570eada
fmt: more ruff fmt formatting
meowtypes May 30, 2026
1216123
bump release version
meowtypes Jun 7, 2026
785ea4b
refactor(ui): polish Add Share dialog and simplify mount_manager_ui code
meowtypes Jun 7, 2026
163c79f
cleanup comments
meowtypes Jun 7, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -5,3 +5,4 @@ dist/
*.AppImage
*.AppImage.sha256
tests/
.superpowers/
88 changes: 88 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,88 @@
# 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. 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`.

## 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` 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`. 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
section.

## Reference docs

- 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
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.
3 changes: 3 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.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=`.
The plaintext password never touches disk, and the encrypted blob is bound to
Expand Down Expand Up @@ -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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@
</categories>

<releases>
<release version="0.1.5" date="2026-05-16" />
<release version="0.1.6" date="2026-05-16" />
</releases>
<content_rating type="oars-1.1" />
</component>
Loading