The Problem

Developers who switch between Windows, WSL‑Linux and macOS spend time manually installing package managers, configuring terminals, and syncing dotfiles. The lack of a single, repeatable workflow makes onboarding new machines error‑prone and forces duplicated effort across OSes.

What This Does

The repository provides a cross‑platform Python TUI (TermTk‑based) that discovers the host OS, presents grouped actions (e.g., install packages, configure WSL, set Windows‑Terminal defaults) and executes them through thin wrappers around the native package managers.

  • Core UI: src/awesome_os/frontend/main.py (entry point main) and src/awesome_os/frontend/runner.py.
  • Package catalog: src/awesome_os/config/packages.yaml drives the concrete managers in src/awesome_os/tasks/managers/ (UbuntuAPT, UbuntuSnap, ArchYay, WindowsWinget, DarwinBrew).
  • System‑level helpers live under src/awesome_os/tasks/system/ (e.g., font.py, zsh.py, windows_wsl_tasks.py).

The one‑liner installers (install_unix.sh, install_windows.ps1) simply bootstrap the Python environment and launch the UI.

How It Is Wired

Execution starts at src/awesome_os/frontend/main.py:125 → main. main builds the UI and, on user action, calls run in src/awesome_os/tasks/commands.py:37.

  • run is a thin dispatcher (called from 28 places) that builds a command line (join_argv) and launches it via subprocess.Popen.
  • Most UI actions funnel through TaskResult (created in src/awesome_os/tasks/task.py) – it is returned by 35 distinct callers and aggregates success/failure status.
  • The most widely used internal helpers are:
  • sudo_non_interactive_ok (6 callers) – runs privileged commands without prompting.
  • is_installed / _ensure_* (5‑7 callers each) – wrap package‑manager checks.
  • Files that touch the outside world:
  • main → sudo_preauth (subprocess).
  • run_app → build_packages_for_os (reads packages.yaml).
  • run (subprocess).

The import graph shows no circular dependencies and 30 internal modules each isolated, which simplifies static reasoning but also means the UI logic is spread across many small files. The deepest nesting (8 levels) appears in src/awesome_os/tasks/factory.py, src/awesome_os/frontend/controller.py and src/awesome_os/tasks/system/font.py, making those sections harder to follow.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/awesome-os-setup.git
cd awesome-os-setup

# Install Python deps (uv or pip)
uv sync           # uses pyproject.toml
# or: pip install -r <(uv pip compile pyproject.toml)

# Launch the UI
python -m src.awesome_os.frontend.main   # entry point main()
  • No additional environment variables are required; the repository ships an .env.example for optional overrides.
  • To run the one‑liner installers instead of the UI, execute sh install_unix.sh on Linux/WSL/macOS or powershell -ExecutionPolicy Bypass -File install_windows.ps1 on Windows (admin).

Real‑World Use

A sysadmin on a fresh Windows 11 machine runs the PowerShell one‑liner. The script installs Winget, pulls the GlazeWM tiling manager, configures Windows Terminal with the JetBrains Mono font, and then launches the TUI. From the UI they select “Install Ubuntu WSL distro → Install GPU drivers”, and the tool calls src/awesome_os/tasks/system/windows_wsl_tasks.py:wsl_install which invokes the wsl.exe CLI via subprocess.run. All actions are logged through ui_log in controller.py.

Code Health & Issues

  • High – Missing test suite – 30 source files have no accompanying tests. Add at least one test per public entry point and enable CI execution.
  • Medium – GitHub token permissions – .github/workflows/build-docs.yml declares no permissions; default token is overly permissive. Add permissions: { contents: read } and scope per job.
  • Medium – Unpinned Docker base image – tests/archlinux/Dockerfile uses mutable tag archlinux:base. Pin to a digest (archlinux@sha256:…) and enable Dependabot for Docker.
  • Medium – No dependency‑vulnerability scan – No workflow runs a vulnerability review. Add dependency-review-action or osv-scanner on PRs.
  • Low – Missing job timeouts – All workflows lack timeout-minutes; set a realistic bound (e.g., 30 min) to avoid runaway runs.
  • Medium – Duplicated manager code – Six manager files repeat ~9 identical 6‑line blocks. Refactor shared logic into a helper module.
  • Medium – Broad exception handling – Files detect_os.py, font.py, zsh.py catch generic Exception. Replace with specific exception types and log unexpected errors.
  • Medium – Deep nesting – Max indentation depth of 8 in several modules; restructure with early returns or helper extraction to improve readability.
  • Low – No lockfile – Dependencies are declared only in pyproject.toml; consider adding uv.lock or poetry.lock for reproducible builds.

The Bottom Line

The repo delivers a functional, cross‑OS setup UI and a solid collection of scripts, but the codebase suffers from maintainability issues (deep nesting, duplicated blocks, broad exception handling) and lacks automated testing and reproducible dependency management. It is suitable for engineers comfortable refactoring and adding CI safeguards, especially those who need a quick, opinionated starter for Windows‑WSL‑Linux development environments.