config.py

"""Portable configuration: locate, load, and save ``poltergeist.json``.

Config always lives next to the running executable (or, in dev, next to
``main.py``) so the whole app is copy-paste portable.

Distribution bootstrap
----------------------

A distributor can drop a **``poltergeist-defaults.json``** next to the
executable before shipping (e.g. inside the onboarding ZIP). On first
launch - i.e. when no ``poltergeist.json`` exists yet - the defaults
file is loaded as the starting config and persisted on the next save.
This lets new hires unpack the ZIP, double-click the exe, and be
dropped straight into a working setup with the team share path, the
database paths, the context patterns, and an example snippet already
filled in.

The defaults file is ignored on subsequent launches - once the user
has a ``poltergeist.json`` it is the only source of truth. Deleting
``poltergeist.json`` and restarting the app therefore acts as a
"factory reset" that re-bootstraps from the shipped defaults.
"""

from __future__ import annotations

import json
import os
import sys
from pathlib import Path
from typing import Any

CONFIG_FILENAME = "poltergeist.json"
DEFAULTS_FILENAME = "poltergeist-defaults.json"


def app_dir() -> Path:
    """Directory the running app lives in (portable anchor)."""
    if getattr(sys, "frozen", False):
        return Path(sys.executable).resolve().parent
    return Path(__file__).resolve().parent


def resource_path(relative: str) -> Path:
    """Locate a bundled resource in dev and inside a PyInstaller one-file build."""
    base = getattr(sys, "_MEIPASS", None)
    if base:
        candidate = Path(base) / relative
        if candidate.exists():
            return candidate
    return app_dir() / relative


def config_path() -> Path:
    return app_dir() / CONFIG_FILENAME


def defaults_path() -> Path:
    """Location of the distribution bootstrap template, if any. The
    file is optional - absence is the common case for dev checkouts
    and for users who have already run the app once."""
    return app_dir() / DEFAULTS_FILENAME


def default_config() -> dict[str, Any]:
    return {
        "version": 2,
        "settings": {
            "hotkey": "ctrl+alt+space",
            "default_injection": "clipboard",
            "default_date_format": "%d/%m/%Y",
            "start_with_windows": False,
            "theme": "auto",
            "deepl_api_key": "",
            "language": "",
            "team_share_path": "",
            "team_shortcuts": {},
            "context_patterns": [],
        },
        "tree_personal": [],
        "tree_team": [],
    }


def _read_json_file(path: Path) -> Any:
    """Read ``path`` as JSON, returning ``None`` if the file is absent,
    unreadable, or not valid JSON. Swallowing these errors is the
    right move here - a bad config must never take the whole app down
    at startup; the caller gets to decide on a fallback."""
    if not path.exists():
        return None
    try:
        with path.open("r", encoding="utf-8") as fh:
            return json.load(fh)
    except (OSError, json.JSONDecodeError):
        return None


def _strip_pseudo_comments(data: dict[str, Any]) -> dict[str, Any]:
    """Return a shallow copy of ``data`` with any pseudo-comment keys
    removed. JSON has no native comment syntax, so the defaults
    template uses leading-underscore keys (``_README``, ``_comment_*``,
    ``_note``, ...) as stand-ins. They exist purely to make the
    template self-documenting for distributors and must not leak into
    the runtime config or they would round-trip into the user's
    ``poltergeist.json`` and pile up over time."""
    return {k: v for k, v in data.items() if not k.startswith("_")}


def _merge_into_default(data: Any) -> dict[str, Any]:
    """Project arbitrary (possibly old-schema) JSON onto the current
    v2 config shape, filling gaps from :func:`default_config`. Used
    both for loading ``poltergeist.json`` and for bootstrapping from
    ``poltergeist-defaults.json`` so the two paths share one set of
    migration / validation rules."""
    merged = default_config()
    if not isinstance(data, dict):
        return merged
    settings = data.get("settings")
    if isinstance(settings, dict):
        merged["settings"].update(_strip_pseudo_comments(settings))
    if isinstance(data.get("tree_personal"), list):
        merged["tree_personal"] = data["tree_personal"]
    elif isinstance(data.get("tree"), list):
        merged["tree_personal"] = data["tree"]
    if isinstance(data.get("tree_team"), list):
        merged["tree_team"] = data["tree_team"]
    if "version" in data:
        merged["version"] = data["version"]
    return merged


def load() -> dict[str, Any]:
    """Load the on-disk config, migrating older versions on the fly
    and bootstrapping from a shipped defaults file when appropriate.

    Resolution order:

    1. If ``poltergeist.json`` exists next to the exe, it wins
       (normal every-day path, including after the bootstrap).
    2. Otherwise, if ``poltergeist-defaults.json`` is present, load
       it as the starting config. The file remains on disk; a
       subsequent :func:`save` persists the (possibly already
       edited) state to ``poltergeist.json``.
    3. Otherwise, fall back to :func:`default_config` - an empty
       but valid v2 layout.

    Version history:

    * v1: single ``tree`` list, no Team/Personal distinction.
    * v2: ``tree`` becomes ``tree_personal``; ``tree_team`` is added
      alongside it; ``settings`` gains ``team_share_path``,
      ``team_shortcuts``, ``context_patterns``.

    v1 configs are migrated transparently - the old ``tree`` is moved
    to ``tree_personal`` and ``tree_team`` starts empty. We never
    delete the user's data here; :func:`save` re-emits it in the v2
    shape on the next write.
    """
    data = _read_json_file(config_path())
    if data is None:
        data = _read_json_file(defaults_path())
    return _merge_into_default(data)


def bootstrapped_from_defaults() -> bool:
    """True when the current process is running before the first
    ``poltergeist.json`` has been written but a defaults file is
    sitting next to the exe. Useful for UI hints (e.g. a one-shot
    toast telling the user 'settings prefilled from defaults -
    review Options > Team before publishing anything')."""
    return not config_path().exists() and defaults_path().exists()


def save(data: dict[str, Any]) -> None:
    path = config_path()
    path.parent.mkdir(parents=True, exist_ok=True)
    tmp = path.with_suffix(path.suffix + ".tmp")
    with tmp.open("w", encoding="utf-8") as fh:
        json.dump(data, fh, indent=2, ensure_ascii=False)
    os.replace(tmp, path)