hpde-analytics-cli 6.0.7__tar.gz → 6.0.9__tar.gz

{hpde_analytics_cli-6.0.7 → hpde_analytics_cli-6.0.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hpde-analytics-cli
-Version: 6.0.7
+Version: 6.0.9
 Summary: Data analysis and reporting tool for HPDE and Time Trials programs
 Author-email: Kevin Homan <homan13@gmail.com>
 License: MIT
@@ -32,6 +32,7 @@ Requires-Dist: openpyxl>=3.1.0
 Requires-Dist: keyring>=24.0.0
 Requires-Dist: gspread>=6.0.0
 Requires-Dist: google-auth>=2.22.0
+Requires-Dist: platformdirs>=4.0.0
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0.0; extra == "dev"
 Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
@@ -94,16 +95,25 @@ pip install hpde-analytics-cli
    This stores your credentials securely in your system's keyring (macOS Keychain, Windows Credential Locker, or Linux Secret Service).
 
    **Option B: Environment file (Fallback)**
-   ```bash
-   cp .env.example .env
-   ```
-   Edit `.env` and add your MotorsportsReg OAuth credentials:
+
+   Create a `.env` file in the directory you run the tool from:
    ```
    MSR_CONSUMER_KEY=your_consumer_key_here
    MSR_CONSUMER_SECRET=your_consumer_secret_here
    MSR_BASE_URL=https://api.motorsportreg.com
    MSR_CALLBACK_PORT=8089
    ```
+   (Working from a clone, `cp .env.example .env` gives you a starting point.)
+
+   Two locations are searched, in this order:
+
+   | Location | Purpose |
+   | --- | --- |
+   | `.env` in the working directory, or any parent | Per-project settings |
+   | `.env` in the user config directory (below) | Your defaults across all directories |
+
+   The project file wins where both set the same key; the user file supplies anything it
+   leaves out.
 
 2. Check credential status (optional):
    ```bash
@@ -198,6 +208,7 @@ hpde-analytics-cli/
 ├── hpde_analytics_cli/
 │   ├── __init__.py
 │   ├── main.py                   # CLI entry point
+│   ├── paths.py                  # Config, token and output path resolution
 │   ├── auth/
 │   │   ├── __init__.py
 │   │   ├── credentials.py        # Secure credential management
@@ -211,10 +222,35 @@ hpde-analytics-cli/
 │       ├── field_discovery.py    # API field enumeration
 │       └── report_generator.py   # Excel report generation
 ├── output/                       # Export and report output (not in version control)
-├── tokens/                       # OAuth access tokens (not in version control)
 └── tests/                        # Unit tests
 ```
 
+## File Locations
+
+Exports and reports are written relative to **the directory you run the command from**, so
+the tool behaves the same whether installed from PyPI or run from a clone. OAuth tokens go
+to a per-user config directory, so they survive upgrades and stay out of your project
+folders.
+
+| What | Location |
+| --- | --- |
+| Exports and reports | `./output/` in the current directory (override with `--output-dir`) |
+| Field inventory | `./output/field_inventory.json` (override with `--output`) |
+| OAuth access token | user config directory, below |
+| `.env` | current directory or any parent, then the user config directory |
+
+The user config directory is the native location for your platform:
+
+| Platform | Path |
+| --- | --- |
+| Linux | `~/.config/hpde-analytics-cli/` |
+| macOS | `~/Library/Application Support/hpde-analytics-cli/` |
+| Windows | `%LOCALAPPDATA%\hpde-analytics-cli\` |
+
+Set `HPDE_CONFIG_DIR` to override it. The token file is written readable only by you
+(mode `0600` on POSIX systems). A token left by version 6.0.7 or earlier is moved to the
+new location automatically on first run, so you will not need to re-authenticate.
+
 ## Export Structure
 
 Each export creates two data sets:
@@ -313,10 +349,13 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 ## Security Notes
 
 **Important:**
-- Never commit `.env` or `tokens/` directory to version control
+- Never commit a `.env` file to version control
 - OAuth consumer secrets and access tokens must be kept confidential
 - The `.gitignore` file is configured to exclude these sensitive files automatically
 - Use `hpde-analytics-cli --configure` to store credentials securely in your system keyring
+- Access tokens live outside the project in the user config directory, written mode `0600`
+- Exported data contains registrant names and email addresses; `output/` is gitignored, but
+  take the same care with it that you would with any roster
 
 ## Support
 

{hpde_analytics_cli-6.0.7 → hpde_analytics_cli-6.0.9}/README.md

@@ -48,16 +48,25 @@ pip install hpde-analytics-cli
    This stores your credentials securely in your system's keyring (macOS Keychain, Windows Credential Locker, or Linux Secret Service).
 
    **Option B: Environment file (Fallback)**
-   ```bash
-   cp .env.example .env
-   ```
-   Edit `.env` and add your MotorsportsReg OAuth credentials:
+
+   Create a `.env` file in the directory you run the tool from:
    ```
    MSR_CONSUMER_KEY=your_consumer_key_here
    MSR_CONSUMER_SECRET=your_consumer_secret_here
    MSR_BASE_URL=https://api.motorsportreg.com
    MSR_CALLBACK_PORT=8089
    ```
+   (Working from a clone, `cp .env.example .env` gives you a starting point.)
+
+   Two locations are searched, in this order:
+
+   | Location | Purpose |
+   | --- | --- |
+   | `.env` in the working directory, or any parent | Per-project settings |
+   | `.env` in the user config directory (below) | Your defaults across all directories |
+
+   The project file wins where both set the same key; the user file supplies anything it
+   leaves out.
 
 2. Check credential status (optional):
    ```bash
@@ -152,6 +161,7 @@ hpde-analytics-cli/
 ├── hpde_analytics_cli/
 │   ├── __init__.py
 │   ├── main.py                   # CLI entry point
+│   ├── paths.py                  # Config, token and output path resolution
 │   ├── auth/
 │   │   ├── __init__.py
 │   │   ├── credentials.py        # Secure credential management
@@ -165,10 +175,35 @@ hpde-analytics-cli/
 │       ├── field_discovery.py    # API field enumeration
 │       └── report_generator.py   # Excel report generation
 ├── output/                       # Export and report output (not in version control)
-├── tokens/                       # OAuth access tokens (not in version control)
 └── tests/                        # Unit tests
 ```
 
+## File Locations
+
+Exports and reports are written relative to **the directory you run the command from**, so
+the tool behaves the same whether installed from PyPI or run from a clone. OAuth tokens go
+to a per-user config directory, so they survive upgrades and stay out of your project
+folders.
+
+| What | Location |
+| --- | --- |
+| Exports and reports | `./output/` in the current directory (override with `--output-dir`) |
+| Field inventory | `./output/field_inventory.json` (override with `--output`) |
+| OAuth access token | user config directory, below |
+| `.env` | current directory or any parent, then the user config directory |
+
+The user config directory is the native location for your platform:
+
+| Platform | Path |
+| --- | --- |
+| Linux | `~/.config/hpde-analytics-cli/` |
+| macOS | `~/Library/Application Support/hpde-analytics-cli/` |
+| Windows | `%LOCALAPPDATA%\hpde-analytics-cli\` |
+
+Set `HPDE_CONFIG_DIR` to override it. The token file is written readable only by you
+(mode `0600` on POSIX systems). A token left by version 6.0.7 or earlier is moved to the
+new location automatically on first run, so you will not need to re-authenticate.
+
 ## Export Structure
 
 Each export creates two data sets:
@@ -267,10 +302,13 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 ## Security Notes
 
 **Important:**
-- Never commit `.env` or `tokens/` directory to version control
+- Never commit a `.env` file to version control
 - OAuth consumer secrets and access tokens must be kept confidential
 - The `.gitignore` file is configured to exclude these sensitive files automatically
 - Use `hpde-analytics-cli --configure` to store credentials securely in your system keyring
+- Access tokens live outside the project in the user config directory, written mode `0600`
+- Exported data contains registrant names and email addresses; `output/` is gitignored, but
+  take the same care with it that you would with any roster
 
 ## Support
 

{hpde_analytics_cli-6.0.7 → hpde_analytics_cli-6.0.9}/hpde_analytics_cli/auth/oauth.py

@@ -19,6 +19,8 @@ from urllib.parse import parse_qs, urlparse
 
 from requests_oauthlib import OAuth1Session
 
+from hpde_analytics_cli import paths
+
 # Default callback port for local OAuth flow
 DEFAULT_CALLBACK_PORT = 8089
 
@@ -147,8 +149,12 @@ class MSROAuth:
 
         # Token storage
         if token_file is None:
-            project_root = Path(__file__).parent.parent.parent
-            self.token_file = project_root / "tokens" / "access_token.json"
+            self.token_file = paths.token_file()
+            # Only when using the default location: an explicit token_file (tests, or a
+            # caller managing its own state) must never have a stray file moved into it.
+            migrated_from = paths.migrate_legacy_token(self.token_file)
+            if migrated_from:
+                print(f"Moved access token from {migrated_from} to {self.token_file}")
         else:
             self.token_file = Path(token_file)
 
@@ -190,8 +196,9 @@ class MSROAuth:
         return False
 
     def _save_tokens(self) -> None:
-        """Save access tokens to file."""
+        """Save access tokens to file, readable only by the owner."""
         self.token_file.parent.mkdir(parents=True, exist_ok=True)
+        paths.restrict_permissions(self.token_file.parent)
 
         data = {
             "access_token": self.access_token,
@@ -203,6 +210,9 @@ class MSROAuth:
         with open(self.token_file, "w") as f:
             json.dump(data, f, indent=2)
 
+        # The file holds the access token and its secret; keep it off other accounts.
+        paths.restrict_permissions(self.token_file)
+
         print(f"Access tokens saved to {self.token_file}")
 
     def has_valid_tokens(self) -> bool:

{hpde_analytics_cli-6.0.7 → hpde_analytics_cli-6.0.9}/hpde_analytics_cli/main.py

@@ -14,7 +14,7 @@ from typing import Any, Dict, Optional
 
 from dotenv import load_dotenv
 
-from hpde_analytics_cli import __version__
+from hpde_analytics_cli import __version__, paths
 from hpde_analytics_cli.api.client import create_client_from_oauth
 from hpde_analytics_cli.auth.credentials import CredentialManager
 from hpde_analytics_cli.auth.oauth import MSROAuth, create_oauth_from_env
@@ -104,7 +104,7 @@ def handle_discover(oauth, args) -> None:
     client = create_client_from_oauth(oauth, organization_id=args.org_id)
     api_data = fetch_api_data(client, event_id=args.event_id, verbose=args.verbose)
 
-    output_path = Path(__file__).parent.parent / args.output
+    output_path = Path(args.output)
     run_field_discovery(api_data, output_path=str(output_path))
 
 
@@ -167,7 +167,7 @@ def handle_export(oauth, args) -> None:
     if args.output_dir:
         output_dir = Path(args.output_dir)
     else:
-        output_dir = Path(__file__).parent.parent / "output"
+        output_dir = paths.default_output_dir()
 
     exporter = DataExporter(output_dir=str(output_dir), name=args.name)
     exported_files = exporter.export_all_data(
@@ -284,14 +284,19 @@ def handle_full_flow(oauth, args) -> None:
     client = create_client_from_oauth(oauth, organization_id=args.org_id)
     api_data = fetch_api_data(client, event_id=args.event_id, verbose=args.verbose)
 
-    output_path = Path(__file__).parent.parent / args.output
+    output_path = Path(args.output)
     run_field_discovery(api_data, output_path=str(output_path))
 
 
 def load_environment(verbose: bool = False) -> None:
-    """Load environment variables from .env file if it exists."""
-    env_path = Path(__file__).parent.parent / ".env"
-    if env_path.exists():
+    """
+    Load environment variables from .env files.
+
+    Loads the project .env (searched upward from the working directory) before the
+    per-user one. load_dotenv leaves already-set keys alone, so the project file wins and
+    the user file fills in whatever it omits.
+    """
+    for env_path in paths.find_env_files():
         load_dotenv(env_path)
         if verbose:
             print(f"Loaded environment from {env_path}")

hpde_analytics_cli-6.0.9/hpde_analytics_cli/paths.py

@@ -0,0 +1,123 @@
+"""
+Filesystem path resolution.
+
+Single owner for every user-facing path the CLI reads or writes.
+
+Paths must never be derived from ``__file__``. For an installed package that resolves to
+``site-packages``, which previously meant the user's ``.env`` was never read, OAuth tokens
+were written where the next upgrade destroys them, and exported registration data landed
+in a library directory. See CODE_REVIEW.md #2.
+"""
+
+import os
+from pathlib import Path
+from typing import List, Optional
+
+from dotenv import find_dotenv
+from platformdirs import user_config_dir
+
+APP_NAME = "hpde-analytics-cli"
+
+#: Overrides the per-user config directory. Mainly for tests and sandboxed front-ends.
+ENV_CONFIG_DIR = "HPDE_CONFIG_DIR"
+
+ENV_FILENAME = ".env"
+OUTPUT_DIRNAME = "output"
+TOKEN_FILENAME = "access_token.json"
+LEGACY_TOKEN_DIRNAME = "tokens"
+
+
+def config_dir() -> Path:
+    """
+    Per-user configuration directory.
+
+    Honours ``HPDE_CONFIG_DIR`` if set, otherwise the platform-native location:
+    ``~/.config/hpde-analytics-cli`` on Linux, ``~/Library/Application Support/...`` on
+    macOS, ``%LOCALAPPDATA%\\...`` on Windows.
+    """
+    override = os.environ.get(ENV_CONFIG_DIR)
+    if override:
+        return Path(override).expanduser()
+    return Path(user_config_dir(APP_NAME))
+
+
+def token_file() -> Path:
+    """Path to the stored OAuth access token."""
+    return config_dir() / TOKEN_FILENAME
+
+
+def default_output_dir() -> Path:
+    """Default directory for exports and reports, relative to where the user is."""
+    return Path.cwd() / OUTPUT_DIRNAME
+
+
+def find_env_files() -> List[Path]:
+    """
+    ``.env`` files to load, in precedence order.
+
+    The project file comes first: ``load_dotenv`` does not overwrite keys that are already
+    set, so loading in this order gives a project-local ``.env`` precedence over the
+    per-user one, which then supplies anything the project file left out.
+    """
+    found: List[Path] = []
+
+    project_env = find_dotenv(ENV_FILENAME, usecwd=True)
+    if project_env:
+        found.append(Path(project_env))
+
+    user_env = config_dir() / ENV_FILENAME
+    if user_env.exists() and user_env not in found:
+        found.append(user_env)
+
+    return found
+
+
+def legacy_token_file() -> Path:
+    """
+    Where versions up to 6.0.7 stored the access token.
+
+    Derived from ``__file__`` the way the old code did, so it resolves to the repository
+    root for a source checkout and to ``site-packages`` for an installed package.
+    """
+    return Path(__file__).parent.parent / LEGACY_TOKEN_DIRNAME / TOKEN_FILENAME
+
+
+def migrate_legacy_token(destination: Path) -> Optional[Path]:
+    """
+    Move a token left by an older version into ``destination``.
+
+    Does nothing if the destination already exists or there is nothing to move, so it is
+    safe to call on every startup.
+
+    Returns:
+        The path moved from, or None if nothing was migrated.
+    """
+    if destination.exists():
+        return None
+
+    legacy = legacy_token_file()
+    if not legacy.is_file():
+        return None
+
+    try:
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        destination.write_bytes(legacy.read_bytes())
+        restrict_permissions(destination)
+        legacy.unlink()
+    except OSError:
+        return None
+
+    return legacy
+
+
+def restrict_permissions(path: Path) -> None:
+    """
+    Restrict a file to the owner (0600), or a directory to 0700.
+
+    Best effort: POSIX permissions do not map onto Windows ACLs, so failures are ignored
+    rather than breaking an otherwise working auth flow.
+    """
+    try:
+        os.chmod(path, 0o700 if path.is_dir() else 0o600)
+    except OSError:
+        pass

{hpde_analytics_cli-6.0.7 → hpde_analytics_cli-6.0.9}/hpde_analytics_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hpde-analytics-cli
-Version: 6.0.7
+Version: 6.0.9
 Summary: Data analysis and reporting tool for HPDE and Time Trials programs
 Author-email: Kevin Homan <homan13@gmail.com>
 License: MIT
@@ -32,6 +32,7 @@ Requires-Dist: openpyxl>=3.1.0
 Requires-Dist: keyring>=24.0.0
 Requires-Dist: gspread>=6.0.0
 Requires-Dist: google-auth>=2.22.0
+Requires-Dist: platformdirs>=4.0.0
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0.0; extra == "dev"
 Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
@@ -94,16 +95,25 @@ pip install hpde-analytics-cli
    This stores your credentials securely in your system's keyring (macOS Keychain, Windows Credential Locker, or Linux Secret Service).
 
    **Option B: Environment file (Fallback)**
-   ```bash
-   cp .env.example .env
-   ```
-   Edit `.env` and add your MotorsportsReg OAuth credentials:
+
+   Create a `.env` file in the directory you run the tool from:
    ```
    MSR_CONSUMER_KEY=your_consumer_key_here
    MSR_CONSUMER_SECRET=your_consumer_secret_here
    MSR_BASE_URL=https://api.motorsportreg.com
    MSR_CALLBACK_PORT=8089
    ```
+   (Working from a clone, `cp .env.example .env` gives you a starting point.)
+
+   Two locations are searched, in this order:
+
+   | Location | Purpose |
+   | --- | --- |
+   | `.env` in the working directory, or any parent | Per-project settings |
+   | `.env` in the user config directory (below) | Your defaults across all directories |
+
+   The project file wins where both set the same key; the user file supplies anything it
+   leaves out.
 
 2. Check credential status (optional):
    ```bash
@@ -198,6 +208,7 @@ hpde-analytics-cli/
 ├── hpde_analytics_cli/
 │   ├── __init__.py
 │   ├── main.py                   # CLI entry point
+│   ├── paths.py                  # Config, token and output path resolution
 │   ├── auth/
 │   │   ├── __init__.py
 │   │   ├── credentials.py        # Secure credential management
@@ -211,10 +222,35 @@ hpde-analytics-cli/
 │       ├── field_discovery.py    # API field enumeration
 │       └── report_generator.py   # Excel report generation
 ├── output/                       # Export and report output (not in version control)
-├── tokens/                       # OAuth access tokens (not in version control)
 └── tests/                        # Unit tests
 ```
 
+## File Locations
+
+Exports and reports are written relative to **the directory you run the command from**, so
+the tool behaves the same whether installed from PyPI or run from a clone. OAuth tokens go
+to a per-user config directory, so they survive upgrades and stay out of your project
+folders.
+
+| What | Location |
+| --- | --- |
+| Exports and reports | `./output/` in the current directory (override with `--output-dir`) |
+| Field inventory | `./output/field_inventory.json` (override with `--output`) |
+| OAuth access token | user config directory, below |
+| `.env` | current directory or any parent, then the user config directory |
+
+The user config directory is the native location for your platform:
+
+| Platform | Path |
+| --- | --- |
+| Linux | `~/.config/hpde-analytics-cli/` |
+| macOS | `~/Library/Application Support/hpde-analytics-cli/` |
+| Windows | `%LOCALAPPDATA%\hpde-analytics-cli\` |
+
+Set `HPDE_CONFIG_DIR` to override it. The token file is written readable only by you
+(mode `0600` on POSIX systems). A token left by version 6.0.7 or earlier is moved to the
+new location automatically on first run, so you will not need to re-authenticate.
+
 ## Export Structure
 
 Each export creates two data sets:
@@ -313,10 +349,13 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 ## Security Notes
 
 **Important:**
-- Never commit `.env` or `tokens/` directory to version control
+- Never commit a `.env` file to version control
 - OAuth consumer secrets and access tokens must be kept confidential
 - The `.gitignore` file is configured to exclude these sensitive files automatically
 - Use `hpde-analytics-cli --configure` to store credentials securely in your system keyring
+- Access tokens live outside the project in the user config directory, written mode `0600`
+- Exported data contains registrant names and email addresses; `output/` is gitignored, but
+  take the same care with it that you would with any roster
 
 ## Support
 

{hpde_analytics_cli-6.0.7 → hpde_analytics_cli-6.0.9}/hpde_analytics_cli.egg-info/SOURCES.txt

@@ -3,6 +3,7 @@ README.md
 pyproject.toml
 hpde_analytics_cli/__init__.py
 hpde_analytics_cli/main.py
+hpde_analytics_cli/paths.py
 hpde_analytics_cli.egg-info/PKG-INFO
 hpde_analytics_cli.egg-info/SOURCES.txt
 hpde_analytics_cli.egg-info/dependency_links.txt
@@ -27,4 +28,5 @@ tests/test_data_export.py
 tests/test_email_populator.py
 tests/test_google_sheets.py
 tests/test_main.py
+tests/test_paths.py
 tests/test_report_generator.py

{hpde_analytics_cli-6.0.7 → hpde_analytics_cli-6.0.9}/hpde_analytics_cli.egg-info/requires.txt

@@ -5,6 +5,7 @@ openpyxl>=3.1.0
 keyring>=24.0.0
 gspread>=6.0.0
 google-auth>=2.22.0
+platformdirs>=4.0.0
 
 [dev]
 pytest>=7.0.0

{hpde_analytics_cli-6.0.7 → hpde_analytics_cli-6.0.9}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "hpde-analytics-cli"
-version = "6.0.7"  # x-release-please-version
+version = "6.0.9"  # x-release-please-version
 description = "Data analysis and reporting tool for HPDE and Time Trials programs"
 readme = "README.md"
 license = {text = "MIT"}
@@ -43,6 +43,7 @@ dependencies = [
     "keyring>=24.0.0",
     "gspread>=6.0.0",
     "google-auth>=2.22.0",
+    "platformdirs>=4.0.0",
 ]
 
 [project.optional-dependencies]

{hpde_analytics_cli-6.0.7 → hpde_analytics_cli-6.0.9}/tests/test_main.py

@@ -7,6 +7,7 @@ from unittest.mock import MagicMock, patch
 
 import pytest
 
+from hpde_analytics_cli import paths
 from hpde_analytics_cli.main import (
     create_parser,
     handle_credential_commands,
@@ -211,35 +212,51 @@ class TestHandleCredentialCommands:
 class TestLoadEnvironment:
     """Tests for load_environment function."""
 
+    @pytest.fixture(autouse=True)
+    def isolated_env(self, tmp_path, monkeypatch):
+        """Run in an empty directory with the user config dir pointed somewhere empty."""
+        work = tmp_path / "work"
+        work.mkdir()
+        monkeypatch.chdir(work)
+        monkeypatch.setenv(paths.ENV_CONFIG_DIR, str(tmp_path / "config"))
+        return work
+
     @patch("hpde_analytics_cli.main.load_dotenv")
-    @patch("hpde_analytics_cli.main.Path")
-    def test_loads_env_when_exists(self, mock_path, mock_load_dotenv):
-        """Test that .env is loaded when it exists."""
-        mock_env_path = MagicMock()
-        mock_env_path.exists.return_value = True
-        mock_path.return_value.__truediv__.return_value.__truediv__.return_value = mock_env_path
+    def test_loads_env_from_working_directory(self, mock_load_dotenv, isolated_env):
+        """A .env beside the user, not beside the installed package, is what gets read."""
+        env_file = isolated_env / ".env"
+        env_file.write_text("MSR_BASE_URL=https://example.test\n")
 
         load_environment(verbose=False)
 
         mock_load_dotenv.assert_called_once()
+        assert mock_load_dotenv.call_args[0][0].resolve() == env_file.resolve()
+
+    @patch("hpde_analytics_cli.main.load_dotenv")
+    def test_loads_project_env_before_user_env(self, mock_load_dotenv, isolated_env, tmp_path):
+        """Project .env is loaded first so its keys win; the user file fills the rest."""
+        project_env = isolated_env / ".env"
+        project_env.write_text("MSR_BASE_URL=https://project.test\n")
+        config = tmp_path / "config"
+        config.mkdir()
+        user_env = config / ".env"
+        user_env.write_text("MSR_CALLBACK_PORT=9999\n")
+
+        load_environment(verbose=False)
+
+        loaded = [call[0][0].resolve() for call in mock_load_dotenv.call_args_list]
+        assert loaded == [project_env.resolve(), user_env.resolve()]
 
     @patch("hpde_analytics_cli.main.load_dotenv")
-    def test_skips_when_no_env(self, mock_load_dotenv, tmp_path):
-        """Test that loading completes without error when .env doesn't exist."""
-        # The function checks if .env exists before calling load_dotenv
-        # This test verifies load_environment handles missing .env gracefully
-        # Note: The actual .env check depends on the installed package location,
-        # so we just verify the function doesn't raise errors
+    def test_skips_when_no_env(self, mock_load_dotenv, isolated_env):
+        """No .env anywhere is not an error, and nothing is loaded."""
         load_environment(verbose=False)
-        # Function should complete without raising an error
+        mock_load_dotenv.assert_not_called()
 
     @patch("hpde_analytics_cli.main.load_dotenv")
-    @patch("hpde_analytics_cli.main.Path")
-    def test_verbose_output(self, mock_path, mock_load_dotenv, capsys):
+    def test_verbose_output(self, mock_load_dotenv, isolated_env, capsys):
         """Test verbose output when loading .env."""
-        mock_env_path = MagicMock()
-        mock_env_path.exists.return_value = True
-        mock_path.return_value.__truediv__.return_value.__truediv__.return_value = mock_env_path
+        (isolated_env / ".env").write_text("MSR_BASE_URL=https://example.test\n")
 
         load_environment(verbose=True)
 

hpde_analytics_cli-6.0.9/tests/test_paths.py

@@ -0,0 +1,168 @@
+"""
+Tests for filesystem path resolution.
+
+The property under test throughout is that no user-facing path depends on where the
+package happens to be installed. See CODE_REVIEW.md #2.
+"""
+
+import json
+import os
+import stat
+import sys
+
+import pytest
+
+from hpde_analytics_cli import paths
+
+
+@pytest.fixture
+def config_dir(tmp_path, monkeypatch):
+    """Point the per-user config directory at a temporary directory."""
+    target = tmp_path / "config"
+    monkeypatch.setenv(paths.ENV_CONFIG_DIR, str(target))
+    return target
+
+
+class TestConfigDir:
+    def test_honours_env_override(self, tmp_path, monkeypatch):
+        monkeypatch.setenv(paths.ENV_CONFIG_DIR, str(tmp_path / "custom"))
+        assert paths.config_dir() == tmp_path / "custom"
+
+    def test_expands_user_in_override(self, monkeypatch):
+        monkeypatch.setenv(paths.ENV_CONFIG_DIR, "~/somewhere")
+        assert "~" not in str(paths.config_dir())
+
+    def test_falls_back_to_platform_location(self, monkeypatch):
+        monkeypatch.delenv(paths.ENV_CONFIG_DIR, raising=False)
+        resolved = paths.config_dir()
+        assert resolved.is_absolute()
+        assert paths.APP_NAME in str(resolved)
+
+    def test_not_inside_site_packages(self, monkeypatch):
+        """The whole point of the module: never resolve into the install location."""
+        monkeypatch.delenv(paths.ENV_CONFIG_DIR, raising=False)
+        package_root = str(os.path.dirname(os.path.dirname(paths.__file__)))
+        assert not str(paths.config_dir()).startswith(package_root)
+
+
+class TestTokenFile:
+    def test_lives_in_config_dir(self, config_dir):
+        assert paths.token_file() == config_dir / paths.TOKEN_FILENAME
+
+    def test_independent_of_working_directory(self, config_dir, tmp_path, monkeypatch):
+        monkeypatch.chdir(tmp_path)
+        first = paths.token_file()
+        sub = tmp_path / "elsewhere"
+        sub.mkdir()
+        monkeypatch.chdir(sub)
+        assert paths.token_file() == first
+
+
+class TestDefaultOutputDir:
+    def test_relative_to_working_directory(self, tmp_path, monkeypatch):
+        monkeypatch.chdir(tmp_path)
+        assert paths.default_output_dir() == tmp_path / paths.OUTPUT_DIRNAME
+
+    def test_follows_working_directory(self, tmp_path, monkeypatch):
+        sub = tmp_path / "events"
+        sub.mkdir()
+        monkeypatch.chdir(sub)
+        assert paths.default_output_dir() == sub / paths.OUTPUT_DIRNAME
+
+
+class TestFindEnvFiles:
+    def test_finds_project_env_in_cwd(self, tmp_path, monkeypatch, config_dir):
+        monkeypatch.chdir(tmp_path)
+        env = tmp_path / ".env"
+        env.write_text("MSR_BASE_URL=https://example.test\n")
+        assert env.resolve() in [p.resolve() for p in paths.find_env_files()]
+
+    def test_searches_upward_from_cwd(self, tmp_path, monkeypatch, config_dir):
+        env = tmp_path / ".env"
+        env.write_text("MSR_BASE_URL=https://example.test\n")
+        nested = tmp_path / "a" / "b"
+        nested.mkdir(parents=True)
+        monkeypatch.chdir(nested)
+        assert env.resolve() in [p.resolve() for p in paths.find_env_files()]
+
+    def test_includes_user_env(self, tmp_path, monkeypatch, config_dir):
+        monkeypatch.chdir(tmp_path)
+        config_dir.mkdir(parents=True)
+        user_env = config_dir / ".env"
+        user_env.write_text("MSR_BASE_URL=https://user.test\n")
+        assert user_env.resolve() in [p.resolve() for p in paths.find_env_files()]
+
+    def test_project_env_takes_precedence(self, tmp_path, monkeypatch, config_dir):
+        monkeypatch.chdir(tmp_path)
+        project_env = tmp_path / ".env"
+        project_env.write_text("MSR_BASE_URL=https://project.test\n")
+        config_dir.mkdir(parents=True)
+        (config_dir / ".env").write_text("MSR_BASE_URL=https://user.test\n")
+
+        found = paths.find_env_files()
+        assert len(found) == 2
+        assert found[0].resolve() == project_env.resolve()
+
+    def test_returns_empty_when_none_exist(self, tmp_path, monkeypatch, config_dir):
+        monkeypatch.chdir(tmp_path)
+        assert paths.find_env_files() == []
+
+
+class TestMigrateLegacyToken:
+    def test_no_op_when_nothing_to_migrate(self, config_dir, monkeypatch, tmp_path):
+        monkeypatch.setattr(paths, "legacy_token_file", lambda: tmp_path / "absent.json")
+        assert paths.migrate_legacy_token(paths.token_file()) is None
+
+    def test_no_op_when_destination_exists(self, config_dir, monkeypatch, tmp_path):
+        legacy = tmp_path / "legacy.json"
+        legacy.write_text('{"access_token": "old"}')
+        monkeypatch.setattr(paths, "legacy_token_file", lambda: legacy)
+
+        destination = paths.token_file()
+        destination.parent.mkdir(parents=True)
+        destination.write_text('{"access_token": "current"}')
+
+        assert paths.migrate_legacy_token(destination) is None
+        assert json.loads(destination.read_text())["access_token"] == "current"
+        assert legacy.exists(), "must not consume the legacy file when it was not used"
+
+    def test_moves_token_and_removes_original(self, config_dir, monkeypatch, tmp_path):
+        legacy = tmp_path / "legacy.json"
+        legacy.write_text('{"access_token": "abc", "access_token_secret": "xyz"}')
+        monkeypatch.setattr(paths, "legacy_token_file", lambda: legacy)
+
+        destination = paths.token_file()
+        assert paths.migrate_legacy_token(destination) == legacy
+        assert json.loads(destination.read_text())["access_token"] == "abc"
+        assert not legacy.exists()
+
+    @pytest.mark.skipif(sys.platform == "win32", reason="POSIX permissions")
+    def test_migrated_token_is_owner_only(self, config_dir, monkeypatch, tmp_path):
+        legacy = tmp_path / "legacy.json"
+        legacy.write_text('{"access_token": "abc"}')
+        os.chmod(legacy, 0o644)
+        monkeypatch.setattr(paths, "legacy_token_file", lambda: legacy)
+
+        destination = paths.token_file()
+        paths.migrate_legacy_token(destination)
+        assert stat.S_IMODE(destination.stat().st_mode) == 0o600
+
+
+class TestRestrictPermissions:
+    @pytest.mark.skipif(sys.platform == "win32", reason="POSIX permissions")
+    def test_file_becomes_owner_only(self, tmp_path):
+        target = tmp_path / "token.json"
+        target.write_text("{}")
+        os.chmod(target, 0o644)
+        paths.restrict_permissions(target)
+        assert stat.S_IMODE(target.stat().st_mode) == 0o600
+
+    @pytest.mark.skipif(sys.platform == "win32", reason="POSIX permissions")
+    def test_directory_becomes_owner_only(self, tmp_path):
+        target = tmp_path / "cfg"
+        target.mkdir(mode=0o755)
+        paths.restrict_permissions(target)
+        assert stat.S_IMODE(target.stat().st_mode) == 0o700
+
+    def test_missing_path_is_ignored(self, tmp_path):
+        paths.restrict_permissions(tmp_path / "does-not-exist")