usage-cli 0.29.32__py3-none-any.whl

usage_dir_sweeper.py

@@ -0,0 +1,100 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright (C) 2026 lollapalooza <https://github.com/aqua5230>
+#
+# Part of "usage". Free software licensed under the GNU Affero General Public
+# License v3.0 only; see the LICENSE file for full terms and the warranty disclaimer.
+
+"""Sweep orphaned ``mkstemp`` remnants out of ``~/.usage/``.
+
+Every atomic write in this project has the same shape: ``mkstemp`` beside the
+target, write, ``os.replace``, and a ``finally`` that unlinks the temp file if
+anything went wrong. That cleanup cannot run when the process is SIGKILLed or
+crashes mid-write, so the ``.tmp`` outlives it — one real install accumulated
+40 MB of them over twelve days, mostly from the large JSONL caches whose long
+writes are the likeliest to be interrupted.
+
+Those write paths are correct and stay untouched. This module only collects
+what a killed process left behind, once, at startup.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import stat
+import time
+from contextlib import suppress
+from pathlib import Path
+
+USAGE_DIR = Path(os.path.expanduser("~/.usage"))
+# Another usage process (for example, the menu bar app and TUI together) may
+# still be writing a large cache. Twenty-four hours is far longer than any
+# single write, so one process cannot remove another process's active temp file.
+STALE_TEMP_AGE_SECONDS = 24 * 3600
+
+logger = logging.getLogger(__name__)
+
+
+def _debug_warning(message: str, *args: object) -> None:
+    with suppress(Exception):
+        if os.environ.get("USAGE_DEBUG") == "1":
+            logger.warning(message, *args, exc_info=True)
+
+
+def _is_real_directory(path: Path) -> bool:
+    try:
+        return stat.S_ISDIR(path.lstat().st_mode)
+    except OSError:
+        return False
+
+
+def _sweep_directory(directory: Path, now: float) -> int:
+    deleted = 0
+    try:
+        entries = directory.iterdir()
+        for path in entries:
+            if not (path.name.startswith("tmp") and path.name.endswith(".tmp")):
+                continue
+            try:
+                file_stat = path.lstat()
+                if not stat.S_ISREG(file_stat.st_mode):
+                    continue
+                if now - file_stat.st_mtime < STALE_TEMP_AGE_SECONDS:
+                    continue
+                path.unlink()
+                deleted += 1
+            except OSError:
+                _debug_warning("failed to inspect or remove stale temp file %s", path)
+    except OSError:
+        _debug_warning("failed to scan usage directory %s", directory)
+    return deleted
+
+
+def sweep_stale_temp_files(root: Path | None = None, *, now: float | None = None) -> int:
+    """Remove stale mkstemp remnants from the usage directory.
+
+    Scans ``root`` plus its direct ``*.d`` children (where the sharded caches
+    put their temp files) and no deeper. Symlinks and directories are never
+    touched no matter how well their name matches. Returns the number deleted;
+    never raises.
+    """
+    deleted = 0
+    try:
+        scan_root = USAGE_DIR if root is None else root
+        current_time = time.time() if now is None else now
+        if not _is_real_directory(scan_root):
+            return 0
+
+        directories = [scan_root]
+        try:
+            for child in scan_root.iterdir():
+                if child.name.endswith(".d") and _is_real_directory(child):
+                    directories.append(child)
+        except OSError:
+            _debug_warning("failed to inspect usage subdirectories in %s", scan_root)
+
+        for directory in directories:
+            deleted += _sweep_directory(directory, current_time)
+    except Exception:
+        _debug_warning("unexpected failure while sweeping stale usage temp files")
+    return deleted

usage_lang.py

@@ -0,0 +1,79 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright (C) 2026 lollapalooza <https://github.com/aqua5230>
+#
+# Part of "usage". Free software licensed under the GNU Affero General Public
+# License v3.0 only; see the LICENSE file for full terms and the warranty disclaimer.
+
+from __future__ import annotations
+
+import os
+import sys
+from collections.abc import Mapping
+
+
+def _normalize_lang(code: str | None) -> str:
+    if not code:
+        return "en"
+    normalized = code.split(".")[0].strip().lower().replace("_", "-")
+
+    if normalized in {"zh-tw", "zh-hk", "zh-hant"} or normalized.startswith(
+        ("zh-tw-", "zh-hant")
+    ):
+        return "zh-TW"
+    if normalized in {"zh-cn", "zh-sg", "zh-hans", "zh"} or normalized.startswith(
+        ("zh-cn-", "zh-hans")
+    ):
+        return "zh-CN"
+    if normalized.startswith("en"):
+        return "en"
+    if normalized.startswith("ja"):
+        return "ja"
+    if normalized.startswith("ko"):
+        return "ko"
+    return "en"
+
+
+def _detect_macos_lang() -> str:
+    try:
+        from Foundation import NSLocale
+
+        preferred = NSLocale.preferredLanguages()
+        if preferred:
+            return _normalize_lang(str(preferred[0]))
+        locale = NSLocale.currentLocale()
+        identifier_attr = getattr(locale, "localeIdentifier", None)
+        identifier = identifier_attr() if callable(identifier_attr) else identifier_attr
+        return _normalize_lang(str(identifier) if identifier is not None else None)
+    except Exception:
+        return "en"
+
+
+def _detect_windows_lang() -> str:
+    try:
+        import ctypes
+        import locale
+
+        windll = getattr(ctypes, "windll", None)
+        if windll is None:
+            return "en"
+        lang_id = int(windll.kernel32.GetUserDefaultUILanguage())
+        return _normalize_lang(locale.windows_locale.get(lang_id))
+    except Exception:
+        return "en"
+
+
+def detect_lang(env: Mapping[str, str] | None = None) -> str:
+    source = os.environ if env is None else env
+    # Windows 上的 LANG 多半是 Git Bash / MSYS 帶進來的，不代表使用者的系統語言。
+    keys = (
+        ("USAGE_LANG", "TT_LANG") if sys.platform == "win32" else ("USAGE_LANG", "TT_LANG", "LANG")
+    )
+    for key in keys:
+        value = source.get(key, "").strip()
+        if value:
+            return _normalize_lang(value)
+    if env is None:
+        if sys.platform == "win32":
+            return _detect_windows_lang()
+        return _detect_macos_lang()
+    return "en"

usage_logging.py

@@ -0,0 +1,75 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright (C) 2026 lollapalooza <https://github.com/aqua5230>
+#
+# Part of "usage". Free software licensed under the GNU Affero General Public
+# License v3.0 only; see the LICENSE file for full terms and the warranty disclaimer.
+
+"""Application logging with bounded rotating file output."""
+
+from __future__ import annotations
+
+import contextlib
+import logging
+import os
+import sys
+from logging.handlers import RotatingFileHandler
+from pathlib import Path
+
+# macOS keeps app logs under ~/Library/Logs; every other platform reuses the
+# ~/.usage directory that already holds the disk caches and the quarantine.
+LOG_DIR = (
+    Path.home() / "Library" / "Logs" / "usage"
+    if sys.platform == "darwin"
+    else Path.home() / ".usage" / "logs"
+)
+LOG_FILENAME = "usage-app.log"
+MAX_BYTES = 2 * 1024 * 1024
+BACKUP_COUNT = 3
+LOG_FORMAT = "%(asctime)s %(name)s %(levelname)s: %(message)s"
+DATE_FORMAT = "%Y-%m-%d %H:%M:%S"
+_GLOBAL_DEBUG_FLAGS = {"1", "all", "*"}
+
+
+class _PrivateRotatingFileHandler(RotatingFileHandler):
+    """Keep the active log private when creation and rotation open a new file."""
+
+    def _open(self):  # type: ignore[no-untyped-def]
+        stream = super()._open()
+        with contextlib.suppress(OSError):
+            os.chmod(self.baseFilename, 0o600)
+        return stream
+
+
+def parse_debug_flags(raw: str | None) -> tuple[bool, list[str]]:
+    """Return whether debug is global and the requested logger names."""
+    flags = [flag.strip().lower() for flag in raw.split(",") if flag.strip()] if raw else []
+    if any(flag in _GLOBAL_DEBUG_FLAGS for flag in flags):
+        return True, []
+    return False, flags
+
+
+def setup_logging() -> None:
+    """Configure console output and best-effort rotating file logging."""
+    global_debug, debug_loggers = parse_debug_flags(os.environ.get("USAGE_DEBUG"))
+    level = logging.DEBUG if global_debug else logging.WARNING
+    logging.basicConfig(level=level, format=LOG_FORMAT, datefmt=DATE_FORMAT)
+
+    root_logger = logging.getLogger()
+    root_logger.setLevel(level)
+    for name in debug_loggers:
+        logging.getLogger(name).setLevel(logging.DEBUG)
+
+    try:
+        LOG_DIR.mkdir(mode=0o700, parents=True, exist_ok=True)
+        file_handler = _PrivateRotatingFileHandler(
+            LOG_DIR / LOG_FILENAME,
+            maxBytes=MAX_BYTES,
+            backupCount=BACKUP_COUNT,
+            encoding="utf-8",
+        )
+    except OSError:
+        return
+
+    file_handler.setLevel(logging.DEBUG)
+    file_handler.setFormatter(logging.Formatter(LOG_FORMAT, datefmt=DATE_FORMAT))
+    root_logger.addHandler(file_handler)

usage_notifications.py

@@ -0,0 +1,96 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright (C) 2026 lollapalooza <https://github.com/aqua5230>
+#
+# Part of "usage". Free software licensed under the GNU Affero General Public
+# License v3.0 only; see the LICENSE file for full terms and the warranty disclaimer.
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Literal
+
+from burn_rate import RESET_DROP_PERCENT
+
+NotificationKind = Literal["warn", "depleted", "restored"]
+
+VALID_CHANNELS = frozenset(
+    {
+        "claude_session",
+        "claude_weekly",
+        "codex_session",
+        "codex_weekly",
+    }
+)
+
+
+@dataclass(slots=True)
+class NotificationEvent:
+    kind: NotificationKind
+    channel: str
+    threshold: float | None
+
+
+@dataclass(slots=True)
+class _ChannelState:
+    last_percent: float | None = None
+    warned_thresholds: set[float] = field(default_factory=set)
+    depleted: bool = False
+
+
+class QuotaNotifier:
+    def __init__(self, thresholds: list[float] | None = None) -> None:
+        values = [90.0] if thresholds is None else thresholds
+        self.thresholds = sorted({float(value) for value in values})
+        self._channels = {channel: _ChannelState() for channel in VALID_CHANNELS}
+
+    def update(
+        self,
+        channels: dict[str, tuple[float | None, bool]],
+    ) -> list[NotificationEvent]:
+        events: list[NotificationEvent] = []
+        for channel, (percent, available) in channels.items():
+            if channel not in VALID_CHANNELS:
+                continue
+            events.extend(self._update_channel(channel, percent, available))
+        return events
+
+    def _update_channel(
+        self,
+        channel: str,
+        percent: float | None,
+        available: bool,
+    ) -> list[NotificationEvent]:
+        state = self._channels[channel]
+        events: list[NotificationEvent] = []
+        current = float(percent) if percent is not None else None
+
+        reset = (
+            current is not None
+            and state.last_percent is not None
+            and (state.last_percent - current) > RESET_DROP_PERCENT
+        )
+        if reset:
+            was_depleted = state.depleted
+            state.warned_thresholds.clear()
+            state.depleted = False
+            if was_depleted and available and current is not None and current < 100.0:
+                events.append(NotificationEvent("restored", channel, None))
+
+        depleted = current is not None and current >= 100.0
+        if depleted:
+            if not state.depleted:
+                events.append(NotificationEvent("depleted", channel, None))
+            state.depleted = True
+        elif current is not None:
+            previous = state.last_percent
+            if previous is not None:
+                for threshold in self.thresholds:
+                    crossed = previous < threshold <= current
+                    if crossed and threshold not in state.warned_thresholds:
+                        events.append(NotificationEvent("warn", channel, threshold))
+                        state.warned_thresholds.add(threshold)
+            state.depleted = False
+
+        if current is not None:
+            state.last_percent = current
+        return events

usage_rate.py

@@ -0,0 +1,97 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright (C) 2026 lollapalooza <https://github.com/aqua5230>
+#
+# Part of "usage". Free software licensed under the GNU Affero General Public
+# License v3.0 only; see the LICENSE file for full terms and the warranty disclaimer.
+
+from __future__ import annotations
+
+import os
+import time
+from collections.abc import Callable
+from datetime import datetime, timezone
+
+from history_loader import UsageEntry, load_entries
+
+BURN_RATE_THRESH_NORMAL = 500.0  # tokens/min
+BURN_RATE_THRESH_ACTIVE = 2500.0
+BURN_RATE_THRESH_HEAVY = 6000.0
+
+GROUP_NAMES = ["Idle", "Normal", "Active", "Heavy"]
+
+
+def _utc_now() -> datetime:
+    return datetime.now(timezone.utc)  # noqa: UP017 - keep timezone.utc explicit.
+
+
+class UsageRateTracker:
+    def __init__(
+        self,
+        forced_group: int | None = None,
+        mock: bool = False,
+        load: Callable[[int], list[UsageEntry]] | None = None,
+    ) -> None:
+        self.forced_group = forced_group
+        self.mock = mock
+        self._load = load
+        self._cached_group: int | None = None
+        self._cache_expires_at = 0.0
+
+    def group(self) -> int:
+        forced_group = self._forced_group()
+        if forced_group is not None:
+            return forced_group
+        if self.mock:
+            return 0
+
+        now = time.monotonic()
+        if self._cached_group is not None and now < self._cache_expires_at:
+            return self._cached_group
+
+        entries = (
+            self._load(1)
+            if self._load is not None
+            else load_entries(hours_back=1)
+        )
+        if not entries:
+            result = 0
+            self._cached_group = result
+            self._cache_expires_at = time.monotonic() + 30
+            return result
+
+        active_tokens = sum(entry.active_tokens for entry in entries)
+        elapsed_seconds = (_utc_now() - entries[0].timestamp).total_seconds()
+        # Match burn_rate's 5-minute floor: a single cache-creation burst should
+        # not trigger Heavy on its own.
+        elapsed_minutes = max(elapsed_seconds / 60.0, 5.0)
+        burn_rate = active_tokens / min(elapsed_minutes, 60.0)
+
+        if burn_rate < BURN_RATE_THRESH_NORMAL:
+            result = 0
+        elif burn_rate < BURN_RATE_THRESH_ACTIVE:
+            result = 1
+        elif burn_rate < BURN_RATE_THRESH_HEAVY:
+            result = 2
+        else:
+            result = 3
+
+        self._cached_group = result
+        self._cache_expires_at = time.monotonic() + 30
+        return result
+
+    def _forced_group(self) -> int | None:
+        if self.forced_group is not None:
+            return self.forced_group
+
+        raw_value = os.environ.get("USAGE_FORCE_GROUP")
+        if raw_value is None:
+            return None
+
+        try:
+            group = int(raw_value)
+        except ValueError:
+            return None
+
+        if 0 <= group < len(GROUP_NAMES):
+            return group
+        return None