feat: LocalSettings module for gitignored local path persistence (#38)

* docs: public-share readiness, dark-mode flythrough, CI improvements

- Fix record_flythrough CLI: --marker_zoom (was --marker_width in docs),
  add required csv positional arg to examples, expand all argparse help
  strings, replace args bullet list with full argument table in README
- Update flythrough map style to dark basemap with teal→amber column
  palette matching the application dark-mode theme; import palette
  constants from components/theme.py for consistency
- Add CI badge, Python 3.9+ badge, and GPL badge to README header
- Update CI branch triggers to cover all conventional commit prefixes
  (feat/*, fix/*, docs/*, refactor/*, chore/*, ci/*, etc.), add pip
  caching, split into named steps, use pip install -e "[dev]"
- Add .pre-commit-config.yaml with ruff and mypy hooks
- Add pyproject.toml [project.dependencies], [project.optional-dependencies.dev],
  [tool.pytest.ini_options], and [tool.coverage] sections; pytest now runs
  with correct flags from config (no manual flag passing needed)
- Correct coverage threshold to 70% (source-only, tests/ excluded from
  measurement; previously 80% was met by inflating numbers with test files)
- Add CHANGELOG.md (Keep a Changelog format)
- Add data/.gitkeep so data/ directory exists after a fresh clone
- Replace assets/example screenshot.png with map and stats variants;
  remove dashboard_mockup.png
- Update flythrough.gif to last 10s of tour at 480px/8fps (3.47 MB,
  within GitHub's 5 MB inline rendering limit)
- Correct Python minimum version from 3.8 to 3.9 in README and pyproject.toml
- Update CLAUDE.md local gate to use bare pytest (flags now in pyproject.toml)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* feat: LocalSettings module for gitignored local path persistence

Replaces the inline data/config.json logic in components/sidebar.py with
a proper core.local_settings.LocalSettings class. Paths are now stored
in local_settings.json at the project root under a nested plugins structure,
making the file easy to pre-populate manually. Adds local_settings.json.example
as a committed template. Also removes a Django-boilerplate gitignore entry
that was incorrectly shadowing core/local_settings.py.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* chore: ignore editor backup files (*~ and .*.un~)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: jschloman

.gitignore

@@ -4,15 +4,15 @@
 each declared config field, then loads the active DataFrame into
 ``st.session_state["df"]`` so every page can access it without reloading.
 
-Path selections are persisted to ``data/config.json`` so they survive
-application restarts and do not need to be re-entered each session.
+Path selections are persisted to ``local_settings.json`` (gitignored) via
+:class:`~core.local_settings.LocalSettings` so they survive application
+restarts and do not need to be re-entered each session.
 """
 
 from __future__ import annotations
 
-import json
 import os
-from typing import Any
+from typing import Any, Callable
 
 import pandas as pd
 import streamlit as st
@@ -26,6 +26,7 @@
     load_swarm_data,
     save_to_cache,
 )
+from core.local_settings import LocalSettings
 from plugins.sources import REGISTRY, load_builtin_plugins
 
 # Detect tkinter availability at import time so the browse button is only
@@ -37,66 +38,33 @@
 except Exception:
     _TKINTER_AVAILABLE = False
 
-_CONFIG_PATH = os.path.join("data", "config.json")
-# Session state key used to track whether we have already loaded the config
-# file into session state in this session.
 _CONFIG_LOADED_KEY = "_autobio_config_loaded"
 
-
-def _read_config() -> dict[str, str]:
-    """Read persisted path config from disk.
-
-    Returns:
-        Dict of session_key → path strings, or an empty dict if the file does
-        not exist or cannot be parsed.
-    """
-    if not os.path.exists(_CONFIG_PATH):
-        return {}
-    try:
-        with open(_CONFIG_PATH) as f:
-            result: dict[str, str] = json.load(f)
-            return result
-    except Exception:
-        return {}
-
-
-def _write_config_entry(session_key: str, value: str) -> None:
-    """Persist a single path entry to the config file on disk.
-
-    Reads the current file (if any), updates the entry, then writes it back
-    atomically to avoid partial-write corruption.
-
-    Args:
-        session_key: The session state key (used as the config file key).
-        value: The path value to persist.
-    """
-    config = _read_config()
-    config[session_key] = value
-    os.makedirs(os.path.dirname(_CONFIG_PATH), exist_ok=True)
-    tmp_path = _CONFIG_PATH + ".tmp"
-    with open(tmp_path, "w") as f:
-        json.dump(config, f, indent=2)
-    os.replace(tmp_path, _CONFIG_PATH)
+# Module-level singleton — reads local_settings.json once on first import.
+_settings = LocalSettings()
 
 
 def _load_config_into_session_state() -> None:
-    """Hydrate session state from the persisted config file (once per session).
+    """Hydrate session state from local_settings.json (once per browser session).
 
     Only runs on the first script execution in a new browser session. Existing
     session state keys are not overwritten so that in-session changes take
     precedence over the saved config.
     """
     if st.session_state.get(_CONFIG_LOADED_KEY):
         return
-    for key, value in _read_config().items():
-        if key not in st.session_state:
-            st.session_state[key] = value
+    for plugin_id, plugin_cfg in _settings.get_all_plugin_configs().items():
+        for field_key, value in plugin_cfg.items():
+            session_key = f"{plugin_id}_{field_key}"
+            if session_key not in st.session_state:
+                st.session_state[session_key] = value
     st.session_state[_CONFIG_LOADED_KEY] = True
 
 
 def _path_input(
     label: str,
     session_key: str,
+    on_persist: Callable[[str], None],
     default: str = "",
     file_types: list[tuple[str, str]] | None = None,
     is_dir: bool = False,
@@ -113,12 +81,14 @@ def _path_input(
     and triggers a rerun. At the top of the *next* run this value is transferred
     to the widget key before the widget is instantiated, which is always allowed.
 
-    Any path selected via the dialog or typed into the text input is persisted
-    to ``data/config.json`` so it survives application restarts.
+    Any path selected via the dialog or typed into the text input is passed to
+    ``on_persist`` so it can be saved to ``local_settings.json``.
 
     Args:
         label: Display label for the text input.
         session_key: Session state key used to persist the path value.
+        on_persist: Callback invoked with the new path string whenever the value
+            changes; responsible for writing to ``local_settings.json``.
         default: Default path value when neither session state nor the saved
             config has an entry for this key.
         file_types: List of (description, glob pattern) tuples for the file
@@ -136,13 +106,12 @@ def _path_input(
     if pending_key in st.session_state:
         value = str(st.session_state.pop(pending_key))
         st.session_state[session_key] = value
-        _write_config_entry(session_key, value)
+        on_persist(value)
     elif session_key not in st.session_state:
         st.session_state[session_key] = default
 
     def _on_change() -> None:
-        """Persist the updated text-input value to the config file."""
-        _write_config_entry(session_key, str(st.session_state.get(session_key, "")))
+        on_persist(str(st.session_state.get(session_key, "")))
 
     if _TKINTER_AVAILABLE:
         # Use st.columns / st.text_input (not st.sidebar.*) so widgets render
@@ -212,9 +181,18 @@ def _render_plugin_config(plugin_id: str, fields: list[dict[str, Any]]) -> dict[
         env_key = f"AUTOBIO_{plugin_id.upper()}_{field['key'].upper()}"
         default = os.getenv(env_key, "")
         is_dir = field.get("type") == "dir_path"
+        field_key = field["key"]
+
+        def _make_persist(fk: str = field_key) -> Callable[[str], None]:
+            def _persist(path: str) -> None:
+                _settings.set_plugin_value(plugin_id, fk, path)
+
+            return _persist
+
         value = _path_input(
             label=field["label"],
             session_key=f"{plugin_id}_{field['key']}",
+            on_persist=_make_persist(),
             default=default,
             file_types=field.get("file_types"),
             is_dir=is_dir,

components/sidebar.py

@@ -0,0 +1,126 @@
+"""Persistent local settings manager for autobiographer.
+
+Settings are stored in ``local_settings.json`` at the project root. That file
+is gitignored so personal paths and preferences never enter version control.
+Copy ``local_settings.json.example`` to ``local_settings.json`` to pre-populate
+plugin paths without going through the UI.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from typing import Any
+
+_DEFAULT_PATH = "local_settings.json"
+
+
+class LocalSettings:
+    """Read/write persistent local settings to a gitignored JSON file.
+
+    Plugin configs are stored under a ``"plugins"`` key, grouped by plugin ID::
+
+        {
+          "plugins": {
+            "lastfm": {"data_path": "/path/to/tracks.csv"},
+            "swarm":  {"swarm_dir": "/path/to/export/"}
+          }
+        }
+
+    Args:
+        path: Path to the settings file. Defaults to ``local_settings.json``
+            relative to the current working directory.
+    """
+
+    def __init__(self, path: str = _DEFAULT_PATH) -> None:
+        self._path = path
+        self._data: dict[str, Any] = self._load()
+
+    def _load(self) -> dict[str, Any]:
+        """Read the settings file from disk.
+
+        Returns:
+            Parsed settings dict, or empty dict if file absent or unreadable.
+        """
+        if not os.path.exists(self._path):
+            return {}
+        try:
+            with open(self._path) as f:
+                data = json.load(f)
+            return data if isinstance(data, dict) else {}
+        except Exception:
+            return {}
+
+    def _save(self) -> None:
+        """Write current settings to disk atomically.
+
+        Uses a tmp-then-rename pattern to prevent partial-write corruption.
+        Creates parent directories as needed.
+        """
+        parent = os.path.dirname(os.path.abspath(self._path))
+        os.makedirs(parent, exist_ok=True)
+        tmp = self._path + ".tmp"
+        with open(tmp, "w") as f:
+            json.dump(self._data, f, indent=2)
+        os.replace(tmp, self._path)
+
+    # ── Plugin config helpers ─────────────────────────────────────────────────
+
+    def get_all_plugin_configs(self) -> dict[str, dict[str, Any]]:
+        """Return stored configs for all plugins.
+
+        Returns:
+            Dict of plugin_id → {field_key: value}. Empty if none saved.
+        """
+        plugins = self._data.get("plugins", {})
+        if not isinstance(plugins, dict):
+            return {}
+        return {k: dict(v) for k, v in plugins.items() if isinstance(v, dict)}
+
+    def get_plugin_config(self, plugin_id: str) -> dict[str, Any]:
+        """Return all stored settings for a single plugin.
+
+        Args:
+            plugin_id: Plugin identifier (e.g. ``"lastfm"``).
+
+        Returns:
+            Dict of field_key → value. Empty dict if no settings saved yet.
+        """
+        return self.get_all_plugin_configs().get(plugin_id, {})
+
+    def set_plugin_value(self, plugin_id: str, field_key: str, value: str) -> None:
+        """Persist a single plugin config value and write to disk.
+
+        Args:
+            plugin_id: Plugin identifier (e.g. ``"lastfm"``).
+            field_key: Config field key (e.g. ``"data_path"``).
+            value: String value to store.
+        """
+        plugins: dict[str, Any] = self._data.setdefault("plugins", {})
+        plugin_cfg: dict[str, str] = plugins.setdefault(plugin_id, {})
+        plugin_cfg[field_key] = value
+        self._save()
+
+    # ── General key/value helpers ─────────────────────────────────────────────
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """Return a top-level setting value.
+
+        Args:
+            key: Setting key.
+            default: Value to return if key is absent.
+
+        Returns:
+            The stored value, or ``default`` if the key is not present.
+        """
+        return self._data.get(key, default)
+
+    def set(self, key: str, value: Any) -> None:
+        """Write a top-level setting value and persist to disk.
+
+        Args:
+            key: Setting key.
+            value: Value to store (must be JSON-serializable).
+        """
+        self._data[key] = value
+        self._save()

core/local_settings.py

@@ -0,0 +1,12 @@
+{
+  "_comment": "Copy this file to local_settings.json (gitignored) and fill in your absolute paths.",
+  "plugins": {
+    "lastfm": {
+      "data_path": "/absolute/path/to/your/lastfm-tracks.csv"
+    },
+    "swarm": {
+      "swarm_dir": "/absolute/path/to/your/swarm-export/",
+      "assumptions_file": "/absolute/path/to/your/default_assumptions.json"
+    }
+  }
+}

local_settings.json.example

@@ -57,7 +57,7 @@ ignore = [
 
 [tool.mypy]
 python_version = "3.9"
-files = ["autobiographer.py", "analysis_utils.py", "visualize.py", "record_flythrough.py", "find_checkin.py", "tools"]
+files = ["autobiographer.py", "analysis_utils.py", "visualize.py", "record_flythrough.py", "find_checkin.py", "tools", "core"]
 ignore_missing_imports = true
 warn_unused_ignores = true
 warn_return_any = true