Decouple non-UI CLI startup from config_ui

Stop aman.py from importing the GTK settings module at module load so version, init, bench, diagnostics, and top-level help can start without pulling in the UI stack.\n\nPromote PyGObject and python-xlib into main project dependencies, switch the documented source install surface to plain uv/pip commands, and teach the portable, deb, and Arch packaging flows to install filtered runtime requirements before the Aman wheel so they still rely on distro-provided GTK/X11 packages.\n\nAdd regression coverage for importing aman with config_ui blocked and for the portable bundle's new requirements payload, then rerun the focused CLI/diagnostics/portable tests plus py_compile.

.github/workflows/ci.yml

@@ -16,7 +16,7 @@ jobs:
         run: |
           python -m pip install --upgrade pip
           python -m pip install uv build
-          uv sync --extra x11
+          uv sync
       - name: Prepare release candidate artifacts
         run: make release-prep
       - name: Upload packaging artifacts

AGENTS.md

@@ -11,7 +11,7 @@
 
 ## Build, Test, and Development Commands
 
-- Install deps (X11): `uv sync --extra x11`.
+- Install deps (X11): `uv sync`.
 - Install deps (Wayland scaffold): `uv sync --extra wayland`.
 - Run daemon: `uv run python3 src/aman.py --config ~/.config/aman/config.json`.
 

Makefile

@@ -83,7 +83,7 @@ release-prep:
 	./scripts/prepare_release.sh
 
 install-local:
-	$(PYTHON) -m pip install --user ".[x11]"
+	$(PYTHON) -m pip install --user .
 
 install-service:
 	mkdir -p $(HOME)/.config/systemd/user

docs/developer-workflows.md

@@ -33,7 +33,7 @@ For `1.0.0`, the manual publication target is the forge release page at
 `uv` workflow:
 
 ```bash
-uv sync --extra x11
+uv sync
 uv run aman run --config ~/.config/aman/config.json
 ```
 

packaging/arch/PKGBUILD.in

@@ -14,6 +14,25 @@ sha256sums=('__TARBALL_SHA256__')
 prepare() {
   cd "${srcdir}/aman-${pkgver}"
   python -m build --wheel
+  python - <<'PY'
+from pathlib import Path
+import re
+import tomllib
+
+project = tomllib.loads(Path("pyproject.toml").read_text(encoding="utf-8"))
+exclude = {"pygobject", "python-xlib"}
+dependencies = project.get("project", {}).get("dependencies", [])
+filtered = []
+for dependency in dependencies:
+    match = re.match(r"\s*([A-Za-z0-9_.-]+)", dependency)
+    if not match:
+        continue
+    name = match.group(1).lower().replace("_", "-")
+    if name in exclude:
+        continue
+    filtered.append(dependency.strip())
+Path("dist/runtime-requirements.txt").write_text("\n".join(filtered) + "\n", encoding="utf-8")
+PY
 }
 
 package() {
@@ -21,7 +40,8 @@ package() {
   install -dm755 "${pkgdir}/opt/aman"
   python -m venv --system-site-packages "${pkgdir}/opt/aman/venv"
   "${pkgdir}/opt/aman/venv/bin/python" -m pip install --upgrade pip
-  "${pkgdir}/opt/aman/venv/bin/python" -m pip install "dist/aman-${pkgver}-"*.whl
+  "${pkgdir}/opt/aman/venv/bin/python" -m pip install --requirement "dist/runtime-requirements.txt"
+  "${pkgdir}/opt/aman/venv/bin/python" -m pip install --no-deps "dist/aman-${pkgver}-"*.whl
 
   install -Dm755 /dev/stdin "${pkgdir}/usr/bin/aman" <<'EOF'
 #!/usr/bin/env bash

packaging/portable/portable_installer.py

@@ -358,6 +358,10 @@ def _copy_bundle_support_files(bundle_dir: Path, stage_dir: Path) -> None:
 def _run_pip_install(bundle_dir: Path, stage_dir: Path, python_tag: str) -> None:
     common_dir = _require_bundle_file(bundle_dir / "wheelhouse" / "common", "common wheelhouse")
     version_dir = _require_bundle_file(bundle_dir / "wheelhouse" / python_tag, f"{python_tag} wheelhouse")
+    requirements_path = _require_bundle_file(
+        bundle_dir / "requirements" / f"{python_tag}.txt",
+        f"{python_tag} runtime requirements",
+    )
     aman_wheel = _aman_wheel(common_dir)
     venv_dir = stage_dir / "venv"
     _run([sys.executable, "-m", "venv", "--system-site-packages", str(venv_dir)])
@@ -372,6 +376,22 @@ def _run_pip_install(bundle_dir: Path, stage_dir: Path, python_tag: str) -> None
             str(common_dir),
             "--find-links",
             str(version_dir),
+            "--requirement",
+            str(requirements_path),
+        ]
+    )
+    _run(
+        [
+            str(venv_dir / "bin" / "python"),
+            "-m",
+            "pip",
+            "install",
+            "--no-index",
+            "--find-links",
+            str(common_dir),
+            "--find-links",
+            str(version_dir),
+            "--no-deps",
             str(aman_wheel),
         ]
     )

pyproject.toml

@@ -29,6 +29,8 @@ dependencies = [
   "llama-cpp-python",
   "numpy",
   "pillow",
+  "PyGObject",
+  "python-xlib",
   "sounddevice",
 ]
 
@@ -36,10 +38,6 @@ dependencies = [
 aman = "aman:main"
 
 [project.optional-dependencies]
-x11 = [
-  "PyGObject",
-  "python-xlib",
-]
 wayland = []
 
 [project.urls]

scripts/package_common.sh

@@ -84,3 +84,30 @@ render_template() {
     sed -i "s|__${key}__|${value}|g" "${output_path}"
   done
 }
+
+write_runtime_requirements() {
+  local output_path="$1"
+  require_command python3
+  python3 - "${output_path}" <<'PY'
+from pathlib import Path
+import re
+import sys
+import tomllib
+
+output_path = Path(sys.argv[1])
+exclude = {"pygobject", "python-xlib"}
+project = tomllib.loads(Path("pyproject.toml").read_text(encoding="utf-8"))
+dependencies = project.get("project", {}).get("dependencies", [])
+filtered = []
+for dependency in dependencies:
+    match = re.match(r"\s*([A-Za-z0-9_.-]+)", dependency)
+    if not match:
+        continue
+    name = match.group(1).lower().replace("_", "-")
+    if name in exclude:
+        continue
+    filtered.append(dependency.strip())
+output_path.parent.mkdir(parents=True, exist_ok=True)
+output_path.write_text("\n".join(filtered) + "\n", encoding="utf-8")
+PY
+}

scripts/package_deb.sh

@@ -21,6 +21,8 @@ fi
 
 build_wheel
 WHEEL_PATH="$(latest_wheel_path)"
+RUNTIME_REQUIREMENTS="${BUILD_DIR}/deb/runtime-requirements.txt"
+write_runtime_requirements "${RUNTIME_REQUIREMENTS}"
 
 STAGE_DIR="${BUILD_DIR}/deb/${PACKAGE_NAME}_${VERSION}_${ARCH}"
 PACKAGE_BASENAME="${PACKAGE_NAME}_${VERSION}_${ARCH}"
@@ -48,7 +50,8 @@ cp "${ROOT_DIR}/packaging/deb/postinst" "${STAGE_DIR}/DEBIAN/postinst"
 chmod 0755 "${STAGE_DIR}/DEBIAN/postinst"
 
 python3 -m venv --system-site-packages "${VENV_DIR}"
-"${VENV_DIR}/bin/python" -m pip install "${PIP_ARGS[@]}" "${WHEEL_PATH}"
+"${VENV_DIR}/bin/python" -m pip install "${PIP_ARGS[@]}" --requirement "${RUNTIME_REQUIREMENTS}"
+"${VENV_DIR}/bin/python" -m pip install "${PIP_ARGS[@]}" --no-deps "${WHEEL_PATH}"
 
 cat >"${STAGE_DIR}/usr/bin/${PACKAGE_NAME}" <<EOF
 #!/usr/bin/env bash

scripts/package_portable.sh

@@ -49,12 +49,22 @@ export_requirements() {
     --python "${python_version}" >"${raw_path}"
   python3 - "${raw_path}" "${output_path}" <<'PY'
 from pathlib import Path
+import re
 import sys
 
 raw_path = Path(sys.argv[1])
 output_path = Path(sys.argv[2])
 lines = raw_path.read_text(encoding="utf-8").splitlines()
-filtered = [line for line in lines if line.strip() != "."]
+exclude = {"pygobject", "python-xlib"}
+filtered = []
+for line in lines:
+    stripped = line.strip()
+    if not stripped or stripped == ".":
+        continue
+    match = re.match(r"([A-Za-z0-9_.-]+)", stripped)
+    if match and match.group(1).lower().replace("_", "-") in exclude:
+        continue
+    filtered.append(line)
 output_path.write_text("\n".join(filtered) + "\n", encoding="utf-8")
 raw_path.unlink()
 PY
@@ -81,6 +91,7 @@ WHEEL_PATH="$(latest_wheel_path)"
 
 rm -rf "${PORTABLE_STAGE_DIR}"
 mkdir -p "${PORTABLE_STAGE_DIR}/wheelhouse/common"
+mkdir -p "${PORTABLE_STAGE_DIR}/requirements"
 mkdir -p "${PORTABLE_STAGE_DIR}/systemd"
 
 cp "${WHEEL_PATH}" "${PORTABLE_STAGE_DIR}/wheelhouse/common/"
@@ -98,14 +109,18 @@ python3 "${ROOT_DIR}/packaging/portable/portable_installer.py" \
   --version "${VERSION}" \
   --output "${PORTABLE_STAGE_DIR}/manifest.json"
 
+TMP_REQ_DIR="${BUILD_DIR}/portable/requirements"
+mkdir -p "${TMP_REQ_DIR}"
+export_requirements "3.10" "${TMP_REQ_DIR}/cp310.txt"
+export_requirements "3.11" "${TMP_REQ_DIR}/cp311.txt"
+export_requirements "3.12" "${TMP_REQ_DIR}/cp312.txt"
+cp "${TMP_REQ_DIR}/cp310.txt" "${PORTABLE_STAGE_DIR}/requirements/cp310.txt"
+cp "${TMP_REQ_DIR}/cp311.txt" "${PORTABLE_STAGE_DIR}/requirements/cp311.txt"
+cp "${TMP_REQ_DIR}/cp312.txt" "${PORTABLE_STAGE_DIR}/requirements/cp312.txt"
+
 if [[ -n "${TEST_WHEELHOUSE_ROOT}" ]]; then
   copy_prebuilt_wheelhouse "${TEST_WHEELHOUSE_ROOT}" "${PORTABLE_STAGE_DIR}/wheelhouse"
 else
-  TMP_REQ_DIR="${BUILD_DIR}/portable/requirements"
-  mkdir -p "${TMP_REQ_DIR}"
-  export_requirements "3.10" "${TMP_REQ_DIR}/cp310.txt"
-  export_requirements "3.11" "${TMP_REQ_DIR}/cp311.txt"
-  export_requirements "3.12" "${TMP_REQ_DIR}/cp312.txt"
   download_python_wheels "cp310" "310" "cp310" "${TMP_REQ_DIR}/cp310.txt" "${PORTABLE_STAGE_DIR}/wheelhouse/cp310"
   download_python_wheels "cp311" "311" "cp311" "${TMP_REQ_DIR}/cp311.txt" "${PORTABLE_STAGE_DIR}/wheelhouse/cp311"
   download_python_wheels "cp312" "312" "cp312" "${TMP_REQ_DIR}/cp312.txt" "${PORTABLE_STAGE_DIR}/wheelhouse/cp312"

src/aman.py

@@ -21,7 +21,6 @@ from typing import Any
 from aiprocess import LlamaProcessor
 from config import Config, ConfigValidationError, load, redacted_dict, save, validate
 from constants import DEFAULT_CONFIG_PATH, MODEL_PATH, RECORD_TIMEOUT_SEC
-from config_ui import ConfigUiResult, run_config_ui, show_about_dialog, show_help_dialog
 from desktop import get_desktop_adapter
 from diagnostics import (
     doctor_command,
@@ -791,6 +790,30 @@ def _app_version() -> str:
         return "0.0.0-dev"
 
 
+def _load_config_ui_attr(attr_name: str) -> Any:
+    try:
+        from config_ui import __dict__ as config_ui_exports
+    except ModuleNotFoundError as exc:
+        missing_name = exc.name or "unknown"
+        raise RuntimeError(
+            "settings UI is unavailable because a required X11 Python dependency "
+            f"is missing ({missing_name})"
+        ) from exc
+    return config_ui_exports[attr_name]
+
+
+def _run_config_ui(*args, **kwargs):
+    return _load_config_ui_attr("run_config_ui")(*args, **kwargs)
+
+
+def _show_help_dialog() -> None:
+    _load_config_ui_attr("show_help_dialog")()
+
+
+def _show_about_dialog() -> None:
+    _load_config_ui_attr("show_about_dialog")()
+
+
 def _read_json_file(path: Path) -> Any:
     if not path.exists():
         raise RuntimeError(f"file does not exist: {path}")
@@ -1446,8 +1469,8 @@ def _run_settings_required_tray(desktop, config_path: Path) -> bool:
         lambda: "settings_required",
         lambda: None,
         on_open_settings=open_settings_callback,
-        on_show_help=show_help_dialog,
-        on_show_about=show_about_dialog,
+        on_show_help=_show_help_dialog,
+        on_show_about=_show_about_dialog,
         on_open_config=lambda: logging.info("config path: %s", config_path),
     )
     return reopen_settings["value"]
@@ -1456,7 +1479,7 @@ def _run_settings_required_tray(desktop, config_path: Path) -> bool:
 def _run_settings_until_config_ready(desktop, config_path: Path, initial_cfg: Config) -> Config | None:
     draft_cfg = initial_cfg
     while True:
-        result: ConfigUiResult = run_config_ui(
+        result = _run_config_ui(
             draft_cfg,
             desktop,
             required=True,
@@ -1665,7 +1688,7 @@ def _run_command(args: argparse.Namespace) -> int:
         if daemon.get_state() != State.IDLE:
             logging.info("settings UI is available only while idle")
             return
-        result = run_config_ui(
+        result = _run_config_ui(
             cfg,
             desktop,
             required=False,
@@ -1740,8 +1763,8 @@ def _run_command(args: argparse.Namespace) -> int:
             daemon.get_state,
             lambda: shutdown("quit requested"),
             on_open_settings=open_settings_callback,
-            on_show_help=show_help_dialog,
-            on_show_about=show_about_dialog,
+            on_show_help=_show_help_dialog,
+            on_show_about=_show_about_dialog,
             is_paused_getter=daemon.is_paused,
             on_toggle_pause=daemon.toggle_paused,
             on_reload_config=reload_config_callback,

src/recorder.py

@@ -102,7 +102,7 @@ def _sounddevice():
         import sounddevice as sd  # type: ignore[import-not-found]
     except ModuleNotFoundError as exc:
         raise RuntimeError(
-            "sounddevice is not installed; install dependencies with `uv sync --extra x11`"
+            "sounddevice is not installed; install dependencies with `uv sync`"
         ) from exc
     return sd
 

tests/test_aman_cli.py

@@ -1,5 +1,6 @@
 import io
 import json
+import subprocess
 import sys
 import tempfile
 import unittest
@@ -242,6 +243,36 @@ class AmanCliTests(unittest.TestCase):
         self.assertEqual(exit_code, 0)
         self.assertEqual(out.getvalue().strip(), "1.2.3")
 
+    def test_version_command_does_not_import_config_ui(self):
+        script = f"""
+import builtins
+import sys
+from pathlib import Path
+
+sys.path.insert(0, {str(SRC)!r})
+real_import = builtins.__import__
+
+def blocked(name, globals=None, locals=None, fromlist=(), level=0):
+    if name == "config_ui":
+        raise ModuleNotFoundError("blocked config_ui")
+    return real_import(name, globals, locals, fromlist, level)
+
+builtins.__import__ = blocked
+import aman
+args = aman._parse_cli_args(["version"])
+raise SystemExit(aman._version_command(args))
+"""
+        result = subprocess.run(
+            [sys.executable, "-c", script],
+            cwd=ROOT,
+            text=True,
+            capture_output=True,
+            check=False,
+        )
+
+        self.assertEqual(result.returncode, 0, result.stderr)
+        self.assertRegex(result.stdout.strip(), r"\S+")
+
     def test_app_version_prefers_local_pyproject_version(self):
         pyproject_text = '[project]\nversion = "9.9.9"\n'
 
@@ -600,7 +631,7 @@ class AmanCliTests(unittest.TestCase):
             with patch("aman._lock_single_instance", return_value=object()), patch(
                 "aman.get_desktop_adapter", return_value=desktop
             ), patch(
-                "aman.run_config_ui",
+                "aman._run_config_ui",
                 return_value=ConfigUiResult(saved=True, config=onboard_cfg, closed_reason="saved"),
             ) as config_ui_mock, patch("aman.Daemon", _FakeDaemon):
                 exit_code = aman._run_command(args)
@@ -618,7 +649,7 @@ class AmanCliTests(unittest.TestCase):
             with patch("aman._lock_single_instance", return_value=object()), patch(
                 "aman.get_desktop_adapter", return_value=desktop
             ), patch(
-                "aman.run_config_ui",
+                "aman._run_config_ui",
                 return_value=ConfigUiResult(saved=False, config=None, closed_reason="cancelled"),
             ), patch("aman.Daemon") as daemon_cls:
                 exit_code = aman._run_command(args)
@@ -640,7 +671,7 @@ class AmanCliTests(unittest.TestCase):
             with patch("aman._lock_single_instance", return_value=object()), patch(
                 "aman.get_desktop_adapter", return_value=desktop
             ), patch(
-                "aman.run_config_ui",
+                "aman._run_config_ui",
                 side_effect=config_ui_results,
             ), patch("aman.Daemon", _FakeDaemon):
                 exit_code = aman._run_command(args)

tests/test_portable_bundle.py

@@ -75,8 +75,10 @@ def _build_fake_wheel(root: Path, version: str) -> Path:
 def _bundle_dir(root: Path, version: str) -> Path:
     bundle_dir = root / f"bundle-{version}"
     (bundle_dir / "wheelhouse" / "common").mkdir(parents=True, exist_ok=True)
+    (bundle_dir / "requirements").mkdir(parents=True, exist_ok=True)
     for tag in portable.SUPPORTED_PYTHON_TAGS:
         (bundle_dir / "wheelhouse" / tag).mkdir(parents=True, exist_ok=True)
+        (bundle_dir / "requirements" / f"{tag}.txt").write_text("", encoding="utf-8")
     (bundle_dir / "systemd").mkdir(parents=True, exist_ok=True)
     shutil.copy2(PORTABLE_DIR / "install.sh", bundle_dir / "install.sh")
     shutil.copy2(PORTABLE_DIR / "uninstall.sh", bundle_dir / "uninstall.sh")
@@ -213,6 +215,9 @@ class PortableBundleTests(unittest.TestCase):
             self.assertIn(f"{prefix}/wheelhouse/cp310", names)
             self.assertIn(f"{prefix}/wheelhouse/cp311", names)
             self.assertIn(f"{prefix}/wheelhouse/cp312", names)
+            self.assertIn(f"{prefix}/requirements/cp310.txt", names)
+            self.assertIn(f"{prefix}/requirements/cp311.txt", names)
+            self.assertIn(f"{prefix}/requirements/cp312.txt", names)
             self.assertIn(f"{prefix}/systemd/aman.service.in", names)
 
     def test_fresh_install_creates_managed_paths_and_starts_service(self):

uv.lock

@@ -16,13 +16,9 @@ dependencies = [
     { name = "numpy", version = "2.2.6", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
     { name = "numpy", version = "2.4.2", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11'" },
     { name = "pillow" },
-    { name = "sounddevice" },
-]
-
-[package.optional-dependencies]
-x11 = [
     { name = "pygobject" },
     { name = "python-xlib" },
+    { name = "sounddevice" },
 ]
 
 [package.metadata]
@@ -31,11 +27,11 @@ requires-dist = [
     { name = "llama-cpp-python" },
     { name = "numpy" },
     { name = "pillow" },
-    { name = "pygobject", marker = "extra == 'x11'" },
-    { name = "python-xlib", marker = "extra == 'x11'" },
+    { name = "pygobject" },
+    { name = "python-xlib" },
     { name = "sounddevice" },
 ]
-provides-extras = ["x11", "wayland"]
+provides-extras = ["wayland"]
 
 [[package]]
 name = "anyio"