iCode-TUI 0.29.1__py3-none-any.whl

chrys/app/tui/i18n.py

@@ -0,0 +1,230 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Plain-text TUI adapters and bounded locale-switch coordination."""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import Protocol, runtime_checkable
+from weakref import WeakSet
+
+from rich.text import Text
+from textual.content import Content
+
+from chrys.foundation.config.settings import DEFAULT_LOCALE, Settings, persist_locale
+from chrys.foundation.config.settings_store import LoadedSettings, SettingsHandle
+from chrys.foundation.i18n import CatalogLoadWarning, Localizer, MessageRef
+from chrys.foundation.i18n.formatting import sanitize_legacy_block, sanitize_legacy_scalar
+
+logger = logging.getLogger(__name__)
+
+
+class LocaleAwareSurface(Protocol):
+    """A live chrome or modal surface that can replace its localized text."""
+
+    def refresh_localization(self) -> None: ...
+
+
+class LocalizationFooter(Protocol):
+    """A mounted registry-resolving footer with an in-place invalidation hook."""
+
+    def invalidate_localization(self) -> None: ...
+
+
+class LocaleSwitchStatus(StrEnum):
+    """Observable outcomes used by confirmation surfaces such as the picker."""
+
+    IDENTICAL_REQUEST = "identical_request"
+    REQUESTED_ONLY = "requested_only"
+    EFFECTIVE_CHANGED = "effective_changed"
+    LOAD_FAILED = "load_failed"
+
+
+@dataclass(frozen=True, slots=True)
+class LocaleSwitchResult:
+    """The completed locale-switch outcome and any catalog warning to present."""
+
+    status: LocaleSwitchStatus
+    warning: CatalogLoadWarning | None = None
+
+
+def _resolved_display_text(localizer: Localizer, reference: MessageRef) -> str:
+    resolved = localizer.render(reference)
+    if reference.definition.multiline:
+        return sanitize_legacy_block(resolved)
+    return sanitize_legacy_scalar(resolved)
+
+
+def render_text(localizer: Localizer, reference: MessageRef) -> Text:
+    """Resolve one semantic message as literal Rich text, never as markup."""
+    return Text(_resolved_display_text(localizer, reference))
+
+
+def render_content(localizer: Localizer, reference: MessageRef) -> Content:
+    """Resolve one semantic message as literal Textual content, never as markup."""
+    return Content.from_text(_resolved_display_text(localizer, reference), markup=False)
+
+
+def render_str(localizer: Localizer, reference: MessageRef) -> str:
+    """Resolve validated plain text for an API whose contract requires ``str``."""
+    return _resolved_display_text(localizer, reference)
+
+
+@runtime_checkable
+class _AppNode(Protocol):
+    """A widget or screen: its ``app`` raises a RuntimeError while no app is active."""
+
+    @property
+    def app(self) -> object: ...
+
+
+@runtime_checkable
+class LocalizedApp(Protocol):
+    """An app that owns a locale controller: ChrysApp, and test hosts that set one."""
+
+    @property
+    def locale_controller(self) -> LocaleController: ...
+
+
+def widget_locale_controller(widget: object) -> LocaleController | None:
+    """Resolve the active app's locale controller for a leaf widget or screen.
+
+    None when the widget is detached or the hosting app is not a ChrysApp
+    (bare test hosts): Textual types ``widget.app`` as a plain ``App``.
+    """
+    if not isinstance(widget, _AppNode):
+        return None
+    try:
+        app = widget.app
+    except RuntimeError:
+        return None
+    return app.locale_controller if isinstance(app, LocalizedApp) else None
+
+
+def widget_localizer(widget: object) -> Localizer:
+    """Resolve the active-app localizer for a leaf widget or screen.
+
+    Falls back to a localizer for the default locale (the system's language)
+    when the widget is detached or the hosting app is not a ChrysApp (bare
+    test hosts).
+    """
+    controller = widget_locale_controller(widget)
+    return Localizer(DEFAULT_LOCALE) if controller is None else controller.localizer
+
+
+class LocaleController:
+    """Own one Localizer and coordinate an O(chrome) locale refresh pass."""
+
+    def __init__(
+        self,
+        settings: Settings | None = None,
+        *,
+        localizer: Localizer | None = None,
+        settings_handle: SettingsHandle | None = None,
+    ) -> None:
+        if settings_handle is not None and settings is not None and settings is not settings_handle.settings:
+            error_message = "Pass either settings or settings_handle, not two different ones."
+            raise ValueError(error_message)
+        # The handle rather than a Settings snapshot: a settings reload
+        # installs a new base into the shared handle, and a snapshot taken
+        # here would keep answering with a locale the app no longer claims.
+        # A bare controller (tests, detached hosts) owns its settings alone.
+        # Writes go through ``override`` in both shapes, so the chosen locale
+        # keeps its provenance and survives later reloads.
+        self._settings_handle = settings_handle or SettingsHandle(
+            LoadedSettings(settings=settings or Settings(), provenance={})
+        )
+        self._localizer = localizer or Localizer(self._settings_handle.settings.locale)
+        self._revision = 0
+        self._surfaces: WeakSet[LocaleAwareSurface] = WeakSet()
+        self._footers: WeakSet[LocalizationFooter] = WeakSet()
+
+    @property
+    def localizer(self) -> Localizer:
+        """Return the live Localizer shared by mount-time presentation paths."""
+        return self._localizer
+
+    @property
+    def requested_locale(self) -> str:
+        """Return the requested value Settings currently hold."""
+        return self._settings_handle.settings.locale
+
+    @property
+    def effective_locale(self) -> str:
+        """Return the locale of the Localizer's active immutable bundle."""
+        return self._localizer.effective_locale
+
+    @property
+    def revision(self) -> int:
+        """Return the number of successfully installed effective-locale changes."""
+        return self._revision
+
+    def register_surface(self, surface: LocaleAwareSurface) -> None:
+        """Weakly register one live surface for text-only locale refreshes.
+
+        Implementations must update text inside already-reserved geometry. The
+        callback must not recompose an outer container, restyle the App, or walk
+        mounted transcript widgets.
+        """
+        self._surfaces.add(surface)
+
+    def unregister_surface(self, surface: LocaleAwareSurface) -> None:
+        """Remove a surface registration before or during unmount."""
+        self._surfaces.discard(surface)
+
+    def register_footer(self, footer: LocalizationFooter) -> None:
+        """Weakly register one mounted registry-resolving footer."""
+        self._footers.add(footer)
+
+    def unregister_footer(self, footer: LocalizationFooter) -> None:
+        """Remove a footer registration before or during unmount."""
+        self._footers.discard(footer)
+
+    def switch_locale(self, requested_locale: str) -> LocaleSwitchResult:
+        """Apply one requested locale, distinguishing persistence from bundle work."""
+        # Identical only when nothing is left to do on either side: Settings
+        # already hold the value AND the bundle was last asked for it. After
+        # a reload changes Settings underneath a still-old bundle, picking
+        # the new value must fall through and finish the switch.
+        if requested_locale == self.requested_locale and requested_locale == self._localizer.requested_locale:
+            return LocaleSwitchResult(LocaleSwitchStatus.IDENTICAL_REQUEST)
+
+        previous_effective = self._localizer.effective_locale
+        warning = self._localizer.switch_locale(requested_locale)
+        if warning is not None:
+            return LocaleSwitchResult(LocaleSwitchStatus.LOAD_FAILED, warning)
+
+        self._settings_handle.override(locale=requested_locale)
+        persist_locale(requested_locale)
+        if self._localizer.effective_locale == previous_effective:
+            return LocaleSwitchResult(LocaleSwitchStatus.REQUESTED_ONLY)
+
+        self._revision += 1
+        self._refresh_registered_presentation()
+        return LocaleSwitchResult(LocaleSwitchStatus.EFFECTIVE_CHANGED)
+
+    def _refresh_registered_presentation(self) -> None:
+        for surface in tuple(self._surfaces):
+            try:
+                surface.refresh_localization()
+            except Exception:
+                logger.exception("Failed to refresh a locale-aware TUI surface.")
+        for footer in tuple(self._footers):
+            try:
+                footer.invalidate_localization()
+            except Exception:
+                logger.exception("Failed to invalidate a localized TUI footer.")
+
+
+__all__ = [
+    "LocaleAwareSurface",
+    "LocaleController",
+    "LocaleSwitchResult",
+    "LocaleSwitchStatus",
+    "LocalizationFooter",
+    "render_content",
+    "render_str",
+    "render_text",
+]

chrys/app/tui/language.py

@@ -0,0 +1,58 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Shared requested-locale choices and localized TUI copy."""
+
+from __future__ import annotations
+
+from chrys.foundation.config.settings import DEFAULT_LOCALE
+from chrys.foundation.i18n import SUPPORTED_LOCALES, MessageDef, msg
+from chrys.foundation.i18n.locale import ENGLISH_LOCALE, SIMPLIFIED_CHINESE_LOCALE
+
+LANGUAGE_PICKER_TITLE = msg(
+    "tui.language_picker.title",
+    fallback="Language",
+)
+LANGUAGE_UNKNOWN_LOCALE = msg(
+    "tui.language_command.unknown_locale",
+    fallback="Unknown /language locale: {locale}",
+)
+
+_LANGUAGE_SYSTEM = msg(
+    "tui.language_picker.system",
+    fallback="Follow System",
+)
+_LANGUAGE_ENGLISH = msg(
+    "tui.language_picker.english",
+    fallback="English",
+)
+_LANGUAGE_SIMPLIFIED_CHINESE = msg(
+    "tui.language_picker.simplified_chinese",
+    fallback="简体中文",
+)
+
+_LANGUAGE_LABELS: dict[str, MessageDef] = {
+    DEFAULT_LOCALE: _LANGUAGE_SYSTEM,
+    ENGLISH_LOCALE: _LANGUAGE_ENGLISH,
+    SIMPLIFIED_CHINESE_LOCALE: _LANGUAGE_SIMPLIFIED_CHINESE,
+}
+
+
+def language_label(locale: str) -> MessageDef | None:
+    """Return the localized display-label definition for *locale*.
+
+    ``None`` for locales without a label (e.g. custom docs languages); callers
+    fall back to the raw locale string.
+    """
+    return _LANGUAGE_LABELS.get(locale)
+
+
+LANGUAGE_OPTIONS = tuple(
+    (requested_locale, _LANGUAGE_LABELS[requested_locale]) for requested_locale in (DEFAULT_LOCALE, *SUPPORTED_LOCALES)
+)
+
+__all__ = [
+    "LANGUAGE_OPTIONS",
+    "LANGUAGE_PICKER_TITLE",
+    "LANGUAGE_UNKNOWN_LOCALE",
+    "language_label",
+]

chrys/app/tui/notifications/__init__.py

@@ -0,0 +1,12 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Desktop notification support for the TUI."""
+
+from chrys.app.tui.notifications.service import NotificationService
+from chrys.app.tui.notifications.settings import NotificationEvent, NotificationSettings
+
+__all__ = [
+    "NotificationEvent",
+    "NotificationService",
+    "NotificationSettings",
+]

chrys/app/tui/notifications/drivers.py

@@ -0,0 +1,180 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Native desktop notification drivers."""
+
+from __future__ import annotations
+
+import asyncio
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Protocol
+
+from chrys.foundation.platform import get_platform
+from chrys.foundation.platform.process import managed_subprocess
+
+_COMMAND_TIMEOUT_SECONDS = 3.0
+_MACOS_SOUND_NAME = "Glass"
+_MACOS_SOUND_PATH = Path("/System/Library/Sounds/Glass.aiff")
+
+
+@dataclass(frozen=True, slots=True)
+class NotificationPayload:
+    """A native notification request."""
+
+    title: str
+    body: str
+    sound: bool = True
+    desktop: bool = True
+
+
+@dataclass(frozen=True, slots=True)
+class NotificationDeliveryResult:
+    """Best-effort delivery result."""
+
+    desktop_sent: bool = False
+    sound_sent: bool = False
+
+
+class NotificationDriver(Protocol):
+    """Async desktop notification driver."""
+
+    async def send(self, payload: NotificationPayload) -> NotificationDeliveryResult:
+        """Send a notification."""
+
+
+async def _run_command(argv: list[str], *, timeout: float = _COMMAND_TIMEOUT_SECONDS) -> bool:
+    """Run a fixed argv command, suppressing output and returning success.
+
+    Spawns via ``managed_subprocess`` — a bare ``create_subprocess_exec``
+    would flash a visible console window on Windows for every PowerShell
+    notification command.
+    """
+    if not argv or not argv[0]:
+        return False
+    try:
+        async with managed_subprocess(
+            *argv,
+            stdin=asyncio.subprocess.DEVNULL,
+            stdout=asyncio.subprocess.DEVNULL,
+            stderr=asyncio.subprocess.DEVNULL,
+        ) as proc:
+            try:
+                await asyncio.wait_for(proc.wait(), timeout=timeout)
+            except TimeoutError:
+                return False
+    except OSError:
+        return False
+    return proc.returncode == 0
+
+
+def _applescript_string(value: str) -> str:
+    """Return a quoted AppleScript string literal."""
+    escaped = value.replace("\\", "\\\\").replace('"', '\\"').replace("\n", "\\n")
+    return f'"{escaped}"'
+
+
+class MacOSNotificationDriver:
+    """macOS native command driver."""
+
+    async def send(self, payload: NotificationPayload) -> NotificationDeliveryResult:
+        desktop_sent = False
+        sound_sent = False
+        if payload.desktop:
+            notifier = shutil.which("terminal-notifier")
+            if notifier:
+                argv = [notifier, "-title", payload.title, "-message", payload.body]
+                if payload.sound:
+                    argv.extend(["-sound", "default"])
+                desktop_sent = await _run_command(argv)
+                sound_sent = desktop_sent and payload.sound
+            else:
+                script = (
+                    f"display notification {_applescript_string(payload.body)} "
+                    f"with title {_applescript_string(payload.title)}"
+                )
+                if payload.sound:
+                    script += f" sound name {_applescript_string(_MACOS_SOUND_NAME)}"
+                desktop_sent = await _run_command(["/usr/bin/osascript", "-e", script])
+                sound_sent = desktop_sent and payload.sound
+        elif payload.sound:
+            sound_sent = await self._play_sound()
+        return NotificationDeliveryResult(desktop_sent=desktop_sent, sound_sent=sound_sent)
+
+    async def _play_sound(self) -> bool:
+        if _MACOS_SOUND_PATH.is_file() and await _run_command(["/usr/bin/afplay", str(_MACOS_SOUND_PATH)]):
+            return True
+        return await _run_command(["/usr/bin/osascript", "-e", "beep 1"])
+
+
+class LinuxNotificationDriver:
+    """Linux native command driver."""
+
+    async def send(self, payload: NotificationPayload) -> NotificationDeliveryResult:
+        desktop_sent = False
+        sound_sent = False
+        notify_send = shutil.which("notify-send")
+        if payload.desktop and notify_send:
+            desktop_sent = await _run_command([notify_send, payload.title, payload.body])
+        if payload.sound:
+            sound_sent = await self._play_sound()
+        return NotificationDeliveryResult(desktop_sent=desktop_sent, sound_sent=sound_sent)
+
+    async def _play_sound(self) -> bool:
+        canberra = shutil.which("canberra-gtk-play")
+        if canberra and await _run_command([canberra, "-i", "message-new-instant"]):
+            return True
+        paplay = shutil.which("paplay")
+        sound_path = Path("/usr/share/sounds/freedesktop/stereo/message.oga")
+        if paplay and sound_path.is_file():
+            return await _run_command([paplay, str(sound_path)])
+        return False
+
+
+def _powershell_string(value: str) -> str:
+    """Return a single-quoted PowerShell string literal."""
+    return "'" + value.replace("'", "''") + "'"
+
+
+class WindowsNotificationDriver:
+    """Windows native command driver."""
+
+    async def send(self, payload: NotificationPayload) -> NotificationDeliveryResult:
+        powershell = shutil.which("powershell") or shutil.which("pwsh")
+        if not powershell:
+            return NotificationDeliveryResult()
+        sound_line = "[System.Media.SystemSounds]::Asterisk.Play();" if payload.sound else ""
+        script = (
+            "Add-Type -AssemblyName System.Windows.Forms;"
+            "Add-Type -AssemblyName System.Drawing;"
+            f"{sound_line}"
+            "$n=New-Object System.Windows.Forms.NotifyIcon;"
+            "$n.Icon=[System.Drawing.SystemIcons]::Information;"
+            f"$n.BalloonTipTitle={_powershell_string(payload.title)};"
+            f"$n.BalloonTipText={_powershell_string(payload.body)};"
+            f"$n.Visible={'$true' if payload.desktop else '$false'};"
+            "if($n.Visible){$n.ShowBalloonTip(5000);Start-Sleep -Milliseconds 1000};"
+            "$n.Dispose();"
+        )
+        argv = [powershell, "-NoProfile", "-NonInteractive", "-Command", script]
+        ok = await _run_command(argv, timeout=5.0)
+        return NotificationDeliveryResult(desktop_sent=ok and payload.desktop, sound_sent=ok and payload.sound)
+
+
+class NullNotificationDriver:
+    """No-op notification driver."""
+
+    async def send(self, payload: NotificationPayload) -> NotificationDeliveryResult:
+        return NotificationDeliveryResult()
+
+
+def default_notification_driver() -> NotificationDriver:
+    """Return the native driver for the current platform."""
+    platform = get_platform()
+    if platform.is_macos:
+        return MacOSNotificationDriver()
+    if platform.is_linux:
+        return LinuxNotificationDriver()
+    if platform.is_windows:
+        return WindowsNotificationDriver()
+    return NullNotificationDriver()

chrys/app/tui/notifications/service.py

@@ -0,0 +1,126 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Runtime notification service for the TUI."""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import logging
+from typing import TYPE_CHECKING
+
+from chrys.app.tui.i18n import render_str
+from chrys.app.tui.notifications.drivers import (
+    NotificationDeliveryResult,
+    NotificationDriver,
+    NotificationPayload,
+    default_notification_driver,
+)
+from chrys.app.tui.notifications.settings import NOTIFICATION_EVENT_LABELS, NotificationEvent, NotificationSettings
+from chrys.foundation.branding import APP_DISPLAY_NAME
+from chrys.foundation.i18n.formatting import format_message
+
+if TYPE_CHECKING:
+    from textual.app import App
+
+    from chrys.app.tui.i18n import LocaleController
+
+logger = logging.getLogger(__name__)
+
+
+class NotificationService:
+    """Coordinates focus-aware desktop notifications for the TUI."""
+
+    def __init__(
+        self,
+        app: App[object],
+        settings: NotificationSettings | None = None,
+        driver: NotificationDriver | None = None,
+        locale_controller: LocaleController | None = None,
+    ) -> None:
+        self._app = app
+        self._settings = settings or NotificationSettings()
+        self._driver = driver or default_notification_driver()
+        self._locale_controller = locale_controller
+        self._focus_known = False
+        self._focused = True
+        self._tasks: set[asyncio.Task[NotificationDeliveryResult]] = set()
+
+    @property
+    def settings(self) -> NotificationSettings:
+        """Current live notification settings."""
+        return self._settings
+
+    def update_settings(self, settings: NotificationSettings) -> None:
+        """Swap live notification settings without reloading the engine."""
+        self._settings = settings
+
+    def set_focused(self, focused: bool) -> None:
+        """Record app focus state from Textual AppFocus/AppBlur events."""
+        self._focus_known = True
+        self._focused = focused
+
+    def notify(self, event: NotificationEvent, *, force: bool = False) -> bool:
+        """Schedule a notification if current settings allow it.
+
+        Returns True when delivery was accepted and scheduled.
+        """
+        try:
+            settings = self._settings
+            if not force and not self._should_notify(event, settings):
+                return False
+            loop = asyncio.get_running_loop()
+            task = loop.create_task(self._deliver(event, settings))
+        except RuntimeError:
+            return False
+        except Exception:
+            logger.debug("Notification scheduling failed", exc_info=True)
+            return False
+        self._tasks.add(task)
+        task.add_done_callback(self._on_task_done)
+        return True
+
+    async def test(self, settings: NotificationSettings | None = None) -> bool:
+        """Send a test notification and report whether any requested channel delivered."""
+        active_settings = settings or self._settings
+        try:
+            result = await self._deliver(NotificationEvent.TURN_COMPLETE, active_settings)
+        except Exception:
+            logger.debug("Test notification delivery failed", exc_info=True)
+            return False
+        return (active_settings.desktop and result.desktop_sent) or (active_settings.sound and result.sound_sent)
+
+    def _should_notify(self, event: NotificationEvent, settings: NotificationSettings) -> bool:
+        if not settings.enabled:
+            return False
+        if not settings.event_enabled(event):
+            return False
+        return not (settings.suppress_when_focused and self._focus_known and self._focused)
+
+    async def _deliver(self, event: NotificationEvent, settings: NotificationSettings) -> NotificationDeliveryResult:
+        title = APP_DISPLAY_NAME
+        reference = NOTIFICATION_EVENT_LABELS[event].bind()
+        controller = self._locale_controller
+        body = format_message(reference) if controller is None else render_str(controller.localizer, reference)
+        payload = NotificationPayload(
+            title=title,
+            body=body,
+            sound=settings.sound,
+            desktop=settings.desktop,
+        )
+        result = await self._driver.send(payload)
+        sound_sent = result.sound_sent
+        if settings.sound and not result.sound_sent:
+            with contextlib.suppress(Exception):
+                self._app.bell()
+                sound_sent = True
+        return NotificationDeliveryResult(desktop_sent=result.desktop_sent, sound_sent=sound_sent)
+
+    def _on_task_done(self, task: asyncio.Task[NotificationDeliveryResult]) -> None:
+        self._tasks.discard(task)
+        try:
+            task.result()
+        except asyncio.CancelledError:
+            pass
+        except Exception:
+            logger.debug("Notification delivery failed", exc_info=True)