Merge remote-tracking branch 'upstream/main'

Author: tomballgithub

README.md

@@ -19,43 +19,79 @@ Powerful real-time tracker for Spotify friend music activity: monitor listening
 <a id="-quick-install-run"></a>
 ### 🚀 Quick Install & Run
 
-Python from PyPI
+#### Python from PyPI
 
 ```sh
 pip install spotify_monitor
+```
+
+Run setup by itself:
+
+```sh
 spotify_monitor --setup
 ```
 
-Docker Compose
+#### Docker image - fastest container setup
+
+##### macOS or Windows
+
+Use a macOS shell or Windows PowerShell with a Docker-compatible runtime that provides the `docker` CLI.
+
+```sh
+docker run --rm --pull=always -it --init -v "${PWD}:/data:z" misiektoja/spotify-monitor:latest --setup
+```
+
+After setup finishes, start monitoring with the files created by the wizard:
+
+```sh
+docker run --rm -it --init -v "${PWD}:/data:z" misiektoja/spotify-monitor:latest --config-file /data/spotify_monitor.conf
+```
+
+The setup command pulls the current image. Both commands keep configuration, private values and output in the current directory.
+
+In Windows Command Prompt replace `${PWD}` with `%cd%`. Windows hosts must use Linux containers.
+
+##### Linux
+
+`--user "$(id -u):$(id -g)"` runs the container with your numeric user and group IDs. This lets the container write files that your host account can edit.
+
+```sh
+docker run --rm --pull=always -it --init --user "$(id -u):$(id -g)" -v "$PWD:/data:z" misiektoja/spotify-monitor:latest --setup
+```
+
+After setup finishes, start monitoring:
 
-On Linux, set the container user to your host user before the first setup command. This lets Spotify Monitor create its configuration and private `.env` file in the current directory. Docker Desktop users on macOS or Windows can skip the two `export` commands.
+```sh
+docker run --rm -it --init --user "$(id -u):$(id -g)" -v "$PWD:/data:z" misiektoja/spotify-monitor:latest --config-file /data/spotify_monitor.conf
+```
+
+#### Docker Compose - shorter recurring commands
+
+Download the Compose file:
 
 ```sh
 curl -fsSLO https://raw.githubusercontent.com/misiektoja/spotify_monitor/refs/heads/main/docker-compose.yml
+```
+
+Linux container engine requires to export your numeric user ID and group ID so files created in the current directory belong to you instead of `root`.
+
+```sh
 export SPOTIFY_MONITOR_UID="$(id -u)"
 export SPOTIFY_MONITOR_GID="$(id -g)"
-docker compose run --rm spotify_monitor --setup
-docker compose up
 ```
 
-Docker run
+Docker-compatible runtimes on macOS and Windows normally do not need these values.
 
-On macOS or Windows with Docker Desktop:
+Run setup by itself:
 
 ```sh
-docker pull misiektoja/spotify-monitor:latest
-docker run --rm -it --init -v "${PWD}:/data:z" misiektoja/spotify-monitor:latest --setup
-docker run --rm -it --init -v "${PWD}:/data:z" misiektoja/spotify-monitor:latest --config-file /data/spotify_monitor.conf
+docker compose run --rm --pull=always spotify_monitor --setup
 ```
 
-The Docker Desktop commands use macOS shell or Windows PowerShell syntax. In Windows Command Prompt replace `${PWD}` with `%cd%`.
-
-On Linux, pass your host user and group so the container can write to the current directory:
+After setup finishes, start monitoring with the shorter recurring command:
 
 ```sh
-docker pull misiektoja/spotify-monitor:latest
-docker run --rm -it --init --user "$(id -u):$(id -g)" -v "$PWD:/data:z" misiektoja/spotify-monitor:latest --setup
-docker run --rm -it --init --user "$(id -u):$(id -g)" -v "$PWD:/data:z" misiektoja/spotify-monitor:latest --config-file /data/spotify_monitor.conf
+docker compose up --no-log-prefix
 ```
 
 For the manual single-file method, optional extras and upgrade commands for every method, see [Installation](https://misiektoja.github.io/spotify_monitor/installation/).
@@ -101,113 +137,50 @@ For Spotify profile and playlist change tracking, see [spotify_profile_monitor](
 
 For Spotify Web Player token and TOTP utilities, see [Debugging Tools](https://misiektoja.github.io/spotify_monitor/debugging/#debugging-tools).
 
-<a id="documentation"></a>
-## Documentation
-
-Full documentation is available at **[misiektoja.github.io/spotify_monitor](https://misiektoja.github.io/spotify_monitor/)**:
-
-- [Installation](https://misiektoja.github.io/spotify_monitor/installation/) - PyPI, manual script, Docker installation and upgrades
-- [Quick Start](https://misiektoja.github.io/spotify_monitor/quick-start/) - setup wizard, authentication and first run
-- [Configuration](https://misiektoja.github.io/spotify_monitor/configuration/) - Spotify login, targets, SMTP, webhooks and secrets
-- [Usage](https://misiektoja.github.io/spotify_monitor/usage/) - command formats, monitoring, container operation, notifications, playback and output
-- [Troubleshooting](https://misiektoja.github.io/spotify_monitor/troubleshooting/) - the `--doctor` self-check and logging levels
-- [Debugging Tools](https://misiektoja.github.io/spotify_monitor/debugging/) - TOTP token testing and secret extraction
-
-<a id="quick-start"></a>
-## Quick Start
-
-<a id="new-here-run-the-setup-wizard"></a>
-### New here? Run the setup wizard
-
-The fastest way to get started is `--setup`. It asks who to monitor, how to connect to Spotify and which alerts you want then saves a ready-to-run configuration. Private values stay in `.env`.
-
-On Linux, set `SPOTIFY_MONITOR_UID="$(id -u)"` and `SPOTIFY_MONITOR_GID="$(id -g)"` before using Docker Compose.
-
-Use the command that matches how you run the tool:
-
-```sh
-# PyPI install
-spotify_monitor --setup
-
-# Manual Python script on macOS or Linux
-python3 spotify_monitor.py --setup
-
-# Manual Python script on Windows
-python spotify_monitor.py --setup
-
-# Docker Compose (skip curl if you cloned the repository)
-curl -fsSLO https://raw.githubusercontent.com/misiektoja/spotify_monitor/refs/heads/main/docker-compose.yml
-docker compose run --rm spotify_monitor --setup
-
-# Docker image on macOS or Windows
-docker run --rm -it --init -v "${PWD}:/data:z" misiektoja/spotify-monitor:latest --setup
-
-# Docker image on Linux
-docker run --rm -it --init --user "$(id -u):$(id -g)" -v "$PWD:/data:z" misiektoja/spotify-monitor:latest --setup
-```
-
-Running the tool with no arguments also offers the wizard when no target has been saved. It detects whether you use PyPI, the downloaded script, Docker or Docker Compose then shows matching commands.
-
 <a id="before-monitoring"></a>
-### Before monitoring
+## Before Monitoring
 
 Spotify only shows a person's listening activity when both of these conditions are met:
 
 1. The Spotify account used by Spotify Monitor follows the person you want to monitor.
 2. That person has enabled listening activity sharing in Spotify.
 
-The setup wizard (`spotify_monitor --setup`) checks whether the configured Spotify account follows the target. It offers to follow only when needed and changes the account only after explicit confirmation. If you want to do it manually, open the person's profile in the Spotify desktop or mobile app then use **Share** > **Copy link to profile**. You can paste the complete profile link into the setup wizard. You do not need to extract the user ID yourself. See [Following the Monitored User](https://misiektoja.github.io/spotify_monitor/configuration/#following-the-monitored-user).
+The setup wizard checks whether the monitoring account follows the target. It can send the follow request after you confirm. To follow manually, open the target's profile in the Spotify desktop or mobile app. You can use **Share** > **Copy link to profile** and paste the complete link into the wizard. You do not need to extract the user ID. See [Following the Monitored User](https://misiektoja.github.io/spotify_monitor/configuration/#following-the-monitored-user).
+
+Firefox import is the recommended login path for local and container installs. See [Container Operation](https://misiektoja.github.io/spotify_monitor/usage/#import-firefox-into-container-authentication) for the host-specific import commands.
 
-For local installs, Firefox import is the recommended login path. Docker users should use the wizard's hidden manual `sp_dc` entry. See the [full Quick Start guide](https://misiektoja.github.io/spotify_monitor/quick-start/) for details.
+<a id="common-commands"></a>
+## Common Commands
 
-<a id="not-sure-which-command-you-need"></a>
-### Not sure which command you need?
+Use [Quick Install & Run](#-quick-install-run) above for first-time setup. The table uses PyPI commands. For manual script, direct Docker and Docker Compose equivalents, see [Run Individual Commands](https://misiektoja.github.io/spotify_monitor/quick-start/#run-individual-commands).
 
 | I want to... | Run this |
 | --- | --- |
-| Set up Spotify Monitor for the first time | Use the setup command for your installation above |
 | Start monitoring with existing authentication | `spotify_monitor TARGET`, where `TARGET` is a raw ID, `spotify:user:` URI or profile URL |
-| Start a target saved as `TARGET_USER_URI_ID` | `spotify_monitor --config-file spotify_monitor.conf` or `docker compose up` |
+| Start a target saved as `TARGET_USER_URI_ID` | `spotify_monitor --config-file spotify_monitor.conf` |
 | Check authentication, connectivity and one target | `spotify_monitor --doctor TARGET` |
 | List Spotify friends visible to the configured account | `spotify_monitor --list-friends` |
 | Import a Spotify login from Firefox | Open [Spotify Web Player](https://open.spotify.com/) in Firefox, sign in then run `spotify_monitor --import-browser-cookie --browser firefox` |
 | Safely set or replace `SP_DC_COOKIE` | Run `spotify_monitor --set-sp-dc` and enter `sp_dc` at the hidden prompt |
 | Configure and test webhook alerts | Use the setup wizard or follow [Webhook Settings](https://misiektoja.github.io/spotify_monitor/configuration/#webhook-settings) |
 
-<a id="manual-commands"></a>
-### Manual commands
-
-The examples below use a PyPI install. For a manual script install, replace `spotify_monitor` with `python3 spotify_monitor.py` on macOS or Linux and `python spotify_monitor.py` on Windows. Docker users can copy the complete command prefixes from the [Usage guide](https://misiektoja.github.io/spotify_monitor/usage/#command-format).
+Running the tool with no arguments offers the wizard if you have not saved a target. If a target is already saved, it starts monitoring that target.
 
-Sign in to [Spotify Web Player](https://open.spotify.com/) with Firefox then import that login:
+For authentication, saved targets, configuration backups and setup recovery, see the [full Quick Start guide](https://misiektoja.github.io/spotify_monitor/quick-start/).
 
-```sh
-spotify_monitor --import-browser-cookie --browser firefox
-```
-
-If browser import is unavailable, enter `sp_dc` through a hidden prompt:
-
-```sh
-spotify_monitor --set-sp-dc
-```
-
-Start monitoring with a raw user ID, Spotify user URI or profile URL. A target saved by the wizard does not need to be repeated:
-
-```sh
-spotify_monitor <spotify_user_uri_id>
-spotify_monitor "https://open.spotify.com/user/spotify_user_uri_id"
-spotify_monitor --config-file spotify_monitor.conf
-```
+For browser profiles, manual cookie extraction, Docker authentication, email and webhook setup, see [Configuration](https://misiektoja.github.io/spotify_monitor/configuration/). For notification choices, playback controls and output files, see [Usage](https://misiektoja.github.io/spotify_monitor/usage/).
 
-Run the self-check or view every command:
+<a id="documentation"></a>
+## Documentation
 
-```sh
-spotify_monitor --doctor <spotify_user_uri_id>
-spotify_monitor --list-friends
-spotify_monitor --help
-```
+Full documentation is available at **[misiektoja.github.io/spotify_monitor](https://misiektoja.github.io/spotify_monitor/)**:
 
-For browser profiles, manual cookie extraction, Docker authentication, email and webhook setup, see [Configuration](https://misiektoja.github.io/spotify_monitor/configuration/). For notification choices, playback controls and output files, see [Usage](https://misiektoja.github.io/spotify_monitor/usage/).
+- [Installation](https://misiektoja.github.io/spotify_monitor/installation/) - PyPI, manual script, Docker installation and upgrades
+- [Quick Start](https://misiektoja.github.io/spotify_monitor/quick-start/) - setup wizard, authentication and first run
+- [Configuration](https://misiektoja.github.io/spotify_monitor/configuration/) - Spotify login, targets, SMTP, webhooks and secrets
+- [Usage](https://misiektoja.github.io/spotify_monitor/usage/) - command formats, monitoring, container operation, notifications, playback and output
+- [Troubleshooting](https://misiektoja.github.io/spotify_monitor/troubleshooting/) - the `--doctor` self-check and logging levels
+- [Debugging Tools](https://misiektoja.github.io/spotify_monitor/debugging/) - TOTP token testing and secret extraction
 
 <a id="change-log"></a>
 ## Change Log

RELEASE_NOTES.md

@@ -2,6 +2,41 @@
 
 This is a high-level summary of the most important changes.
 
+# Changes in 3.1 (23 Jul 2026)
+
+Version **3.1** makes **Docker onboarding portable across macOS, Linux and Windows**. Setup now centers on **host-aware Firefox authentication**, keeps configuration and secrets on the persistent **`/data` bind mount** and carries exact **Doctor and monitoring commands** through recovery.
+
+**Features and improvements**:
+
+- **IMPROVE:** Kept Firefox import as the **recommended Docker authentication path** while making its deferred workflow explicit. Setup now asks whether Docker runs on macOS, standard Linux, Linux with Snap, Linux with Flatpak, Windows PowerShell or Windows Command Prompt then prints the matching read-only profile mount
+- **NEW:** Added **Windows-host Firefox import** for direct Docker and Docker Compose through the normal `%APPDATA%\Mozilla\Firefox` profile root with shell-specific PowerShell and Command Prompt commands
+- **IMPROVE:** Deferred **Doctor until Firefox authentication has been imported**. Container setup now finishes with ordered commands to import the login, verify authentication and the target then start monitoring
+- **IMPROVE:** Preserved **setup guidance across one-time authentication commands** by keeping terminal history visible and repeating the exact Doctor and monitoring commands after a successful Firefox import
+- **IMPROVE:** Printed the **install-aware monitoring command** after a successful Doctor run while preserving explicit or saved targets and selected configuration files
+
+**Bug fixes**:
+
+- **BUGFIX:** Fixed generated Docker commands that used the container UID `10001:10001` and always assumed the Linux `~/.mozilla/firefox` profile path. **macOS commands omit Linux user mapping** while Linux commands resolve the host user and group IDs in the host shell
+- **BUGFIX:** Stopped standalone container recovery guidance from presenting one Linux-only Firefox command when the Docker host is unknown
+- **BUGFIX:** Anchored **default container setup files** to the bind-mounted **`/data` directory** so the generated configuration and dotenv files survive the temporary setup container
+- **BUGFIX:** Rejected **Docker setup destinations outside `/data`** instead of saving ephemeral files then printing commands for different paths
+- **BUGFIX:** Generated direct Docker commands with **`${PWD}` for macOS, Linux and Windows PowerShell** then switched to `%cd%` for Windows Command Prompt while retaining Linux user mapping
+- **BUGFIX:** Saved the **selected dotenv destination** in generated configuration so later config-only starts and secret reloads keep using it
+- **BUGFIX:** Printed an **explicit Compose monitoring command** when setup uses nondefault config or dotenv paths instead of falling back to hardcoded defaults
+- **BUGFIX:** Preserved the selected configuration path through the hidden **`--set-sp-dc` fallback** and its Doctor and monitoring guidance
+- **BUGFIX:** Prevented a **Windows traceback after Ctrl+C** when monitoring was started directly from setup. The setup parent now treats its duplicate console interrupt as the same clean termination already handled by the monitoring child
+
+# Changes in 3.0.1 (22 Jul 2026)
+
+**Features and improvements**:
+
+- **IMPROVE:** Made Firefox login import the recommended Docker and Docker Compose authentication path. A one-time read-only host profile mount imports `sp_dc` into the persistent `.env` file, later runs no longer need the browser mount and hidden manual cookie entry remains available as a fallback
+- **IMPROVE:** Updated `spotify_monitor_totp_test --fetch-secrets` to scan current web-player bundles for inline TOTP secret objects while retaining the original runtime hook for older bundle formats
+
+**Bug fixes**:
+
+- **BUGFIX:** Fixed Docker Compose startup after guided setup. The default service command now loads `/data/.env` explicitly, preventing `docker compose up` from reporting a missing `SP_DC_COOKIE` when setup and doctor already saved and validated it
+
 # Changes in 3.0 (22 Jul 2026)
 
 Version **3.0** focuses on making Spotify Monitor easier to set up, safer to configure and easier to recover when something goes wrong. It adds guided onboarding, simpler Spotify login, Docker Compose, clearer terminal output and Discord + ntfy webhook alerts while keeping advanced client mode available for experienced users.
@@ -117,8 +152,8 @@ Special thanks to [@tomballgithub](https://github.com/tomballgithub) for testing
 
 - **IMPROVE:** Added support for loading TOTP secrets from local files via file:// URLs
 - **IMPROVE:** Updated remote URL in SECRET_CIPHER_DICT_URL
-- **IMPROVE:** Updated  [spotify_monitor_secret_grabber](https://github.com/misiektoja/spotify_monitor/blob/dev/debug/spotify_monitor_secret_grabber.py) to dump secrets in different formats. Choose what you need with the `--secret`,` --secretbytes` and `--secretdict` CLI flags, or go all out with the `--all` mode to write all secret formats to files like `secrets.json`, `secretBytes.json` and `secretDict.json` (thanks [@tomballgithub](https://github.com/tomballgithub))
-- **IMPROVE:** Added multi-arch Docker image build and compose support for  [spotify_monitor_secret_grabber](https://github.com/misiektoja/spotify_monitor/blob/dev/debug/spotify_monitor_secret_grabber.py) - more info at [Secret Key Extraction via Docker](https://misiektoja.github.io/spotify_monitor/debugging/#-secret-key-extraction-via-docker-recommended-easiest-way)
+- **IMPROVE:** Updated  [spotify_monitor_secret_grabber](https://github.com/misiektoja/spotify_monitor/blob/main/debug/spotify_monitor_secret_grabber.py) to dump secrets in different formats. Choose what you need with the `--secret`,` --secretbytes` and `--secretdict` CLI flags, or go all out with the `--all` mode to write all secret formats to files like `secrets.json`, `secretBytes.json` and `secretDict.json` (thanks [@tomballgithub](https://github.com/tomballgithub))
+- **IMPROVE:** Added multi-arch Docker image build and compose support for  [spotify_monitor_secret_grabber](https://github.com/misiektoja/spotify_monitor/blob/main/debug/spotify_monitor_secret_grabber.py) - more info at [Secret Key Extraction via Docker](https://misiektoja.github.io/spotify_monitor/debugging/#secret-key-extraction-via-docker)
 - **IMPROVE:** Added deletion of flag_file at launch if specified via .conf file. Previously only done when flag_file was specified on command line
 - **IMPROVE:** Added info to console output when TOTP secrets are fetched from a remote URL or local file