STT-Assistant/src/stt_daemon/assistant/brief_file.py

"""Best-effort atomic writer for the durable brief markdown snapshot.

Enabled via `[brief].write = true` (off by default). When enabled, each brief
update replaces `[brief].dir`/`[brief].filename` (default `brief/brief.md`)
with the exact text supplied by the assistant, using the same
`tempfile.mkstemp` + `os.replace` atomic pattern as the rest of the codebase.

The `brief/` directory is cwd-relative user state and gitignored. Best-effort
by design: any `OSError` is logged and swallowed so the brief writer can never
disturb the assistant flow; `clear()` truncates to empty and likewise never
raises.
"""

import logging
import os
import tempfile

logger = logging.getLogger(__name__)


class BriefFile:
    """Best-effort, atomic, opt-in writer for the durable brief document."""

    def __init__(self, write_enabled: bool, directory: str, filename: str = "brief.md") -> None:
        self._write_enabled = bool(write_enabled)
        self._directory = str(directory)
        self._filename = str(filename)

    @property
    def write_enabled(self) -> bool:
        return self._write_enabled

    def write(self, text: str) -> None:
        """Atomically replace the brief file with `text` (no-op when disabled)."""
        if not self._write_enabled:
            return
        path = os.path.join(self._directory, self._filename)
        try:
            os.makedirs(self._directory, exist_ok=True)
            fd, tmp = tempfile.mkstemp(dir=self._directory, suffix=".tmp")
            try:
                with os.fdopen(fd, "w", encoding="utf-8") as f:
                    f.write(text)
                os.replace(tmp, path)
            except OSError:
                try:
                    os.unlink(tmp)
                except OSError:
                    pass
                raise
        except OSError as e:  # noqa: BLE001 - brief write is best-effort, never raises
            logger.warning("brief file write failed: %s", e)

    def clear(self) -> None:
        """Truncate the brief file to empty (no-op when disabled; never raises)."""
        if not self._write_enabled:
            return
        path = os.path.join(self._directory, self._filename)
        try:
            with open(path, "w", encoding="utf-8"):
                pass
        except OSError as e:  # noqa: BLE001 - brief clear is best-effort, never raises
            logger.warning("brief file clear failed: %s", e)