core.config¶

@dataclass(frozen=True, slots=True)
class UserConfigField:
    """One user-editable key in ``config.toml`` with default and comment."""

    key: str
    default: Any
    comment: str
    section_title: str | None = None

@dataclass(eq=False)
class UserConfig:
    """Read/write access to ``config.toml`` and ``.user_id`` in a data directory.

    The immutable ``user_id`` lives in a separate ``.user_id`` file so
    it never appears in the user-editable config.  On first run a random
    UUID is generated and written there.

    ``username`` is a free-form display name that can be changed at any
    time without affecting label continuity.

    On first run, if ``config.toml`` is missing, a full commented starter
    template is written once. Existing files are not regenerated on later
    loads.

    Mutations from ``update()`` or property setters persist immediately.
    ``config.toml`` uses ``#`` comments above each known setting.
    """

    data_dir: Path | str = DEFAULT_DATA_DIR
    _dir: Path = field(init=False)
    _path: Path = field(init=False)
    _user_id_path: Path = field(init=False)
    _title_secret_path: Path = field(init=False)
    _data: dict[str, Any] = field(init=False)
    _uid: str = field(init=False)
    _title_secret: str = field(init=False)

    def __post_init__(self) -> None:
        self._dir = Path(self.data_dir)
        self._path = self._dir / _CONFIG_FILENAME
        self._user_id_path = self._dir / _USER_ID_FILENAME
        self._title_secret_path = self._dir / _TITLE_SECRET_FILENAME
        self._migrate_json()
        self._data = self._load()
        self._uid = self._load_user_id()
        self._title_secret = self._load_title_secret()
        self._ensure_starter_config_if_missing()

    # -- migration & loading ---------------------------------------------------

    def _migrate_json(self) -> None:
        """One-time migration from config.json to config.toml + .user_id."""
        json_path = self._dir / _LEGACY_JSON_FILENAME
        if self._path.exists() or not json_path.exists():
            return
        try:
            data = json.loads(json_path.read_text("utf-8"))
            data.pop("_help", None)

            uid = data.pop("user_id", None)
            if uid:
                self._dir.mkdir(parents=True, exist_ok=True)
                self._user_id_path.write_text(uid, "utf-8")

            self._dir.mkdir(parents=True, exist_ok=True)
            self._path.write_text(_to_commented_toml(data), "utf-8")
            json_path.rename(json_path.with_suffix(".json.bak"))
            logger.info(
                "Migrated %s → %s + %s", json_path, self._path, self._user_id_path
            )
        except Exception:
            logger.warning("Failed to migrate %s", json_path, exc_info=True)

    def _load(self) -> dict[str, Any]:
        if self._path.exists():
            try:
                return dict(tomllib.loads(self._path.read_text("utf-8")))
            except tomllib.TOMLDecodeError, OSError:
                logger.warning("Corrupt config at %s — using defaults", self._path)
        return {}

    def _load_user_id(self) -> str:
        """Read or generate the stable user_id from .user_id file."""
        if self._user_id_path.exists():
            uid = self._user_id_path.read_text("utf-8").strip()
            if uid:
                return uid

        # Migrate from config.toml if it was written there by old code
        uid = self._data.pop("user_id", None)
        if uid:
            self._persist_user_id(uid)
            self._persist()
            return uid

        uid = str(uuid.uuid4())
        self._persist_user_id(uid)
        return uid

    def _persist_user_id(self, uid: str) -> None:
        self._dir.mkdir(parents=True, exist_ok=True)
        self._user_id_path.write_text(uid, "utf-8")

    def _load_title_secret(self) -> str:
        """Read, migrate, or generate the stable per-install title secret."""
        if self._title_secret_path.exists():
            secret = self._title_secret_path.read_text("utf-8").strip()
            if secret:
                return secret

        legacy = self._data.pop("title_salt", None)
        if legacy:
            secret = str(legacy).strip()
            if secret:
                self._persist_title_secret(secret)
                self._persist()
                return secret

        secret = secrets.token_hex(32)
        self._persist_title_secret(secret)
        return secret

    def _persist_title_secret(self, secret: str) -> None:
        self._dir.mkdir(parents=True, exist_ok=True)
        self._title_secret_path.write_text(secret, "utf-8")

    def _ensure_starter_config_if_missing(self) -> None:
        """Write the full default template only when ``config.toml`` does not exist."""
        if self._path.exists():
            return
        self._dir.mkdir(parents=True, exist_ok=True)
        self._path.write_text(render_default_user_config_toml(), "utf-8")
        self._data = self._load()

    def _persist(self) -> None:
        self._path.parent.mkdir(parents=True, exist_ok=True)
        self._path.write_text(_to_commented_toml(self._data), "utf-8")

    # -- user_id (stable, read-only after creation) ----------------------------

    @property
    def user_id(self) -> str:
        """Stable UUID assigned to this install.  Never changes."""
        return self._uid

    @property
    def title_secret(self) -> str:
        """Stable per-install secret used for privacy-preserving title featurization."""
        return self._title_secret

    @property
    def title_salt(self) -> str:
        """Backward-compatible alias for the local title secret."""
        return self._title_secret

    # -- username (editable display name) --------------------------------------

    @property
    def username(self) -> str:
        return self._data.get("username", _DEFAULT_USERNAME)

    @username.setter
    def username(self, value: str) -> None:
        value = value.strip()
        if not value:
            raise ValueError("username must not be empty")
        self._data["username"] = value
        self._persist()

    # -- generic helpers -------------------------------------------------------

    def as_dict(self) -> dict[str, Any]:
        return {
            "user_id": self.user_id,
            "username": self.username,
            **{
                k: v
                for k, v in self._data.items()
                if k not in ("user_id", "username", "title_salt", "title_secret")
            },
        }

    def update(self, patch: dict[str, Any]) -> dict[str, Any]:
        """Merge *patch* into the config and persist.  Returns the full config.

        ``user_id`` is ignored in *patch* — it is immutable after creation.
        """
        if "username" in patch:
            name = str(patch["username"]).strip()
            if not name:
                raise ValueError("username must not be empty")
            self._data["username"] = name
        for key, val in patch.items():
            if key in ("user_id", "username", "title_salt", "title_secret"):
                continue
            self._data[key] = val
        self._persist()
        return self.as_dict()