chore(project): add repository scaffolding and build config

shell.nix

@@ -0,0 +1,105 @@
+{ pkgs ? import <nixpkgs> { } }:
+
+# FHS development shell for somafm-tui.
+#
+# Why FHS?  uv installs manylinux wheels from PyPI (notably NumPy) that expect
+# libstdc++.so.6 and friends in the usual FHS locations (/usr/lib, /lib).
+# NixOS doesn't populate those paths, so a normal mkShell fails at runtime with
+#   libstdc++.so.6: cannot open shared object file
+# buildFHSEnv gives us a tiny FHS root with the Nix store mounted, and
+# stdenv.cc.cc.lib supplies the missing C++ runtime.
+#
+#   nix-shell            # enter the FHS shell
+#   rm -rf .venv         # once, if the venv was created by an older setup
+#   uv sync              # install Python deps with uv
+#   uv run somafm-tui    # start the radio
+#
+# Note: `nix-shell --run "..."` is not supported by FHS shell.nix files; enter
+# the shell interactively and run commands there.
+
+(pkgs.buildFHSEnv {
+  name = "somafm-tui";
+
+  targetPkgs = pkgs: with pkgs; [
+    # --- Python toolchain; uv owns all Python dependencies ---------------
+    # Nix's default python3 (not a patch/minor pin).  Outside this shell,
+    # uv accepts any CPython >= 3.10, or downloads one if needed.
+    python3
+    uv
+
+    # --- the actual fix for NumPy/manylinux wheels ------------------------
+    stdenv.cc.cc.lib   # libstdc++.so.6
+    zlib
+
+    # --- radio ------------------------------------------------------------
+    mpv
+    ffmpeg
+    dbus
+    playerctl
+    tmux                 # detect the outer terminal inside tmux for TGP
+
+    # --- audio backends that mpv / ffplay load at runtime -----------------
+    alsa-lib
+    libpulseaudio
+    pipewire
+    pulseaudio          # parec/pactl: synced spectrum capture (works with PipeWire)
+
+    # --- shell / terminal helpers -----------------------------------------
+    bashInteractive
+    ncurses
+    coreutils
+    findutils
+    gnused
+    gnugrep
+    which
+    curl
+    cacert
+    git
+
+    # --- mpv/ffmpeg optional display libs (harmless with --no-video) ------
+    libGL
+    libxkbcommon
+    wayland
+    libx11
+    libxext
+  ];
+
+  profile = ''
+    # Use the shell's interpreter here; this is not a project-wide pin.
+    export UV_PYTHON="${pkgs.python3}/bin/python3"
+    export UV_PYTHON_DOWNLOADS=never
+    export UV_PROJECT_ENVIRONMENT="${toString ./.}/.venv"
+    export UV_LINK_MODE=copy
+    export SSL_CERT_FILE="${pkgs.cacert}/etc/ssl/certs/ca-bundle.crt"
+
+    # Audio/MPRIS sockets live under XDG_RUNTIME_DIR.
+    if [ -z "$XDG_RUNTIME_DIR" ] && [ -d "/run/user/$(id -u)" ]; then
+      export XDG_RUNTIME_DIR="/run/user/$(id -u)"
+    fi
+
+    # A session bus is what lets desktop media widgets see MPRIS.
+    if [ -z "$DBUS_SESSION_BUS_ADDRESS" ] && [ -n "$XDG_RUNTIME_DIR" ] \
+       && [ -S "$XDG_RUNTIME_DIR/bus" ]; then
+      export DBUS_SESSION_BUS_ADDRESS="unix:path=$XDG_RUNTIME_DIR/bus"
+    fi
+
+    export PS1='\[\e[1;35m\][somafm-tui]\[\e[0m\] \w \$ '
+
+    echo ""
+    echo "  somafm-tui — FHS dev shell"
+    echo "  --------------------------"
+    echo "  uv sync            install / update python deps"
+    echo "  uv run somafm-tui  start the radio"
+    echo ""
+    echo "  python : $(python3 --version 2>&1)"
+    echo "  uv     : $(uv --version 2>&1)"
+    echo "  mpv    : $(mpv --version 2>&1 | head -n1)"
+    echo "  ffmpeg : $(ffmpeg -version 2>&1 | head -n1)"
+    echo ""
+    echo "  If NumPy still fails to load, recreate the venv once:"
+    echo "    rm -rf .venv && uv sync"
+    echo ""
+  '';
+
+  runScript = "bash";
+}).env