prompt-command-center 1.0.0__py3-none-any.whl

pcc/__init__.py

@@ -0,0 +1,3 @@
+"""PCC — Prompt Command Center: a keyboard-first prompt template palette."""
+
+__version__ = "1.0.0"

pcc/__main__.py

@@ -0,0 +1,168 @@
+"""Entry point: single-instance guard, tray, IPC wiring, event loop."""
+
+from __future__ import annotations
+
+import ctypes
+import sys
+
+from PySide6.QtCore import QObject, Qt, Signal
+from PySide6.QtGui import QAction, QColor, QFont, QIcon, QPainter, QPainterPath, QPixmap
+from PySide6.QtWidgets import QApplication, QMenu, QSystemTrayIcon
+
+from . import store, winapi
+from .ipc import CMD_QUIT, CMD_SHOW, CMD_TOGGLE, HostWindow, TriggerFilter, find_existing_host
+from .ui.palette import PaletteWindow, load_stylesheet
+
+MUTEX_NAME = "Global\\PCC_PromptCommandCenter_SingleInstance"
+ACCENT = QColor("#22D3EE")
+BACKDROP = QColor("#0B0F14")
+
+
+class ReloadBridge(QObject):
+    """Marshals watchdog's worker-thread callback onto the Qt main thread.
+
+    Touching widgets from the watcher thread would be a crash waiting to happen;
+    a queued signal is the cheap, correct fix.
+    """
+
+    triggered = Signal()
+
+
+def _acquire_single_instance() -> bool:
+    """Claim the named mutex. ``False`` means another PCC already owns it.
+
+    A named mutex rather than a window search: process creation and window
+    creation are not atomic, so two near-simultaneous launches could both find
+    no window and both start.
+    """
+    kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
+    handle = kernel32.CreateMutexW(None, False, MUTEX_NAME)
+    if not handle:
+        return True  # cannot tell; assume we are alone rather than refuse to run
+    ERROR_ALREADY_EXISTS = 183
+    if ctypes.get_last_error() == ERROR_ALREADY_EXISTS:
+        return False
+    # Leaked deliberately: the mutex must outlive this function for the whole
+    # process lifetime, and Windows releases it on exit.
+    _acquire_single_instance._handle = handle  # type: ignore[attr-defined]
+    return True
+
+
+def build_icon() -> QIcon:
+    """Draw the tray glyph rather than shipping a .ico file."""
+    pixmap = QPixmap(64, 64)
+    pixmap.fill(Qt.GlobalColor.transparent)
+
+    painter = QPainter(pixmap)
+    painter.setRenderHint(QPainter.RenderHint.Antialiasing)
+
+    path = QPainterPath()
+    path.addRoundedRect(4, 4, 56, 56, 14, 14)
+    painter.fillPath(path, BACKDROP)
+    painter.setPen(ACCENT)
+    painter.drawPath(path)
+
+    font = QFont("Cascadia Code", 26, QFont.Weight.Bold)
+    painter.setFont(font)
+    painter.setPen(ACCENT)
+    painter.drawText(pixmap.rect(), Qt.AlignmentFlag.AlignCenter, "›_")
+    painter.end()
+
+    return QIcon(pixmap)
+
+
+def main() -> int:
+    if not _acquire_single_instance():
+        # Second launch acts as a trigger for the instance already running --
+        # this is what makes the AHK hybrid fallback safe to fire twice.
+        existing = find_existing_host()
+        if existing:
+            ctypes.WinDLL("user32", use_last_error=True).PostMessageW(
+                ctypes.c_void_p(existing), 0x8000, CMD_SHOW, 0
+            )
+        return 0
+
+    app = QApplication(sys.argv)
+    app.setApplicationName("PCC")
+    app.setQuitOnLastWindowClosed(False)  # the palette hiding must not end the app
+
+    winapi.relax_foreground_lock()
+
+    settings = store.load_settings()
+    app.setStyleSheet(load_stylesheet(settings))
+    library = store.load_library(store.library_path(settings))
+    palette = PaletteWindow(library, settings)
+    palette.quit_requested.connect(app.quit)
+    palette.prewarm()
+
+    host = HostWindow()
+    trigger_filter = TriggerFilter(
+        host.hwnd,
+        {
+            CMD_SHOW: palette.trigger,
+            CMD_TOGGLE: palette.toggle,
+            CMD_QUIT: app.quit,
+        },
+    )
+    app.installNativeEventFilter(trigger_filter)
+    # Only now is the host discoverable by AHK; see HostWindow.arm().
+    host.arm()
+
+    bridge = ReloadBridge()
+    bridge.triggered.connect(palette.reload_library)
+    watcher = store.LibraryWatcher(store.library_path(settings), bridge.triggered.emit)
+    watcher.start()
+
+    # Every internal save must silence the watcher, or we reload our own writes.
+    palette.before_save = watcher.mark_self_write
+
+    icon = build_icon()
+    app.setWindowIcon(icon)
+    tray = QSystemTrayIcon(icon)
+    tray.setToolTip("PCC — CapsLock+Space")
+
+    menu = QMenu()
+    show_action = QAction("Show palette", menu)
+    show_action.triggered.connect(palette.trigger)
+    edit_action = QAction("Edit templates.json", menu)
+    edit_action.triggered.connect(palette.open_library_file)
+    prefs_action = QAction("Settings…\tCtrl+,", menu)
+    prefs_action.triggered.connect(lambda: (palette.trigger(), palette.open_settings()))
+    settings_action = QAction("Edit settings.json", menu)
+    settings_action.triggered.connect(palette.open_settings_file)
+    reload_action = QAction("Reload templates", menu)
+    reload_action.triggered.connect(palette.reload_library)
+    restyle_action = QAction("Reload settings", menu)
+    restyle_action.triggered.connect(palette.reload_settings)
+    quit_action = QAction("Quit PCC\tCtrl+Q", menu)
+    quit_action.triggered.connect(app.quit)
+    menu.addAction(show_action)
+    menu.addAction(prefs_action)
+    menu.addSeparator()
+    menu.addAction(edit_action)
+    menu.addAction(settings_action)
+    menu.addAction(reload_action)
+    menu.addAction(restyle_action)
+    menu.addSeparator()
+    menu.addAction(quit_action)
+
+    tray.setContextMenu(menu)
+    tray.activated.connect(
+        lambda reason: palette.toggle()
+        if reason == QSystemTrayIcon.ActivationReason.Trigger
+        else None
+    )
+    tray.show()
+
+    app.aboutToQuit.connect(watcher.stop)
+    # Flush the debounced usage tail so the last few pastes are not lost on exit.
+    app.aboutToQuit.connect(palette.usage.flush)
+
+    if "--show" in sys.argv:
+        palette.trigger()
+
+    return app.exec()
+
+
+if __name__ == "__main__":
+    sys.exit(main())

pcc/compose.py

@@ -0,0 +1,51 @@
+"""Composition: stack templates and layer modifiers into one prompt.
+
+The trick that keeps this tiny and robust is to compose at the *body* level, not
+with a new runtime object. Joining a few template bodies with blank lines yields
+an ordinary body string, which then flows through the very same
+:func:`pcc.model.render`, :func:`pcc.model.parse_slots` and fill panel as any
+single template -- including the existing rule that a repeated ``{{name}}``
+collapses to one field. So two stacked templates that both use ``{{code}}`` share
+one input for free, with no code here to make that happen.
+
+A *modifier* (a template tagged ``modifier``) is a fragment like "Be concise." or
+"Answer as a markdown table." Marking a handful and applying them to a base is
+what turns N templates into N x M prompts from the same small library.
+"""
+
+from __future__ import annotations
+
+from .model import Template
+
+#: Blank line between parts: it reads as paragraph breaks in the destination
+#: chat box and never accidentally glues the end of one prompt to the next.
+JOIN = "\n\n"
+
+
+def combined_body(bases: list[Template], modifiers: list[Template]) -> str:
+    """Join base bodies then modifier bodies into one prompt body.
+
+    Bases keep their given order (stacking), modifiers follow (so "be concise"
+    lands after the instruction it qualifies). Empty bodies are dropped so a
+    stray blank template cannot open a paste with whitespace.
+    """
+    parts = [t.body.strip() for t in bases if t.body.strip()]
+    parts += [m.body.strip() for m in modifiers if m.body.strip()]
+    return JOIN.join(parts)
+
+
+def compose(bases: list[Template], modifiers: list[Template]) -> Template | None:
+    """A transient :class:`Template` for the joined prompt, or ``None`` if empty.
+
+    Transient by design: it carries a sentinel id and is never stored, so it
+    reuses the whole fill/paste path without touching the library.
+    """
+    body = combined_body(bases, modifiers)
+    if not body:
+        return None
+    if len(bases) == 1 and not modifiers:
+        # A single base with no modifiers is just that base -- keep its identity
+        # so usage recording and slot recall still key off the real template.
+        return bases[0]
+    title = bases[0].title if bases else "Composed"
+    return Template(title=title, body=body, id="__composed__")

pcc/context.py

@@ -0,0 +1,198 @@
+"""Context resolvers: the magic behind ``{{clipboard}}``, ``{{date}}`` and kin.
+
+A *magic slot* is a placeholder whose name is a known context source rather than
+a fill-in the user types. ``{{clipboard}}`` becomes whatever you last copied,
+``{{app}}`` the executable you summoned PCC over, ``{{date}}`` today.
+
+The whole feature is one function injected into :func:`pcc.model.render`: a
+``resolve(name) -> str | None`` closure. ``model`` stays free of Qt and Win32 --
+the promise that keeps it headlessly testable -- because the closure is built
+*here* and passed in, and this module is the one place allowed to touch
+:mod:`pcc.winapi`.
+
+The slow-path contract is deliberately built in from day one, even though every
+resolver today is instant. A :class:`Resolved` may report ``pending``; a
+pending value renders to the literal token, exactly like an unavailable one, and
+the paste path never blocks. An LLM-backed slot later is just a resolver that
+stays pending for 900 ms -- no structural change needed then.
+"""
+
+from __future__ import annotations
+
+import datetime as _dt
+from collections.abc import Callable
+from dataclasses import dataclass
+
+from . import winapi
+
+
+@dataclass
+class ResolveEnv:
+    """Everything a resolver may read, captured at trigger time.
+
+    Captured rather than read live so a resolver is a pure function of this
+    snapshot: the target window has moved on by the time the user picks a
+    template, and tests can supply the whole world without a real desktop.
+    """
+
+    target_hwnd: int = 0
+    #: Clipboard text at trigger time. ``None`` means "read it live"; a string
+    #: (including "") means "use exactly this", which is what lets tests and the
+    #: selection-capture path (wave 5) override it.
+    clipboard: str | None = None
+    #: Selection captured from the target app. Reserved for wave 5; until then it
+    #: stays ``None`` and ``{{selection}}`` resolves to the literal token.
+    selection: str | None = None
+    now: _dt.datetime | None = None
+
+    def _clipboard(self) -> str:
+        if self.clipboard is not None:
+            return self.clipboard
+        return winapi.clipboard_get_text() or ""
+
+    def _now(self) -> _dt.datetime:
+        return self.now or _dt.datetime.now()
+
+
+@dataclass(frozen=True)
+class Resolved:
+    """A resolver's answer.
+
+    ``value`` is ``None`` when the source has nothing (empty clipboard, unknown
+    window); ``pending`` marks a slow source still working. Both render to the
+    literal token, so an unresolved magic slot degrades to precisely what an
+    unfilled ordinary slot does today.
+    """
+
+    value: str | None
+    pending: bool = False
+
+    @property
+    def available(self) -> bool:
+        return self.value is not None and not self.pending
+
+
+# --- The registry -----------------------------------------------------------
+#
+# Each entry maps a magic name to a pure function of the env. Adding a source is
+# one line here; nothing else in the app needs to know the name exists.
+
+Resolver = Callable[[ResolveEnv], Resolved]
+
+
+def _some(text: str | None) -> Resolved:
+    """Wrap a plain string: empty or ``None`` becomes an unavailable Resolved."""
+    return Resolved(text if text else None)
+
+
+RESOLVERS: dict[str, Resolver] = {
+    "clipboard": lambda env: _some(env._clipboard()),
+    "selection": lambda env: _some(env.selection),
+    "date": lambda env: _some(env._now().strftime("%Y-%m-%d")),
+    "time": lambda env: _some(env._now().strftime("%H:%M")),
+    "datetime": lambda env: _some(env._now().strftime("%Y-%m-%d %H:%M")),
+    "app": lambda env: _some(winapi.process_name(env.target_hwnd)),
+    "window": lambda env: _some(winapi.window_title(env.target_hwnd)),
+}
+
+#: Human labels for the fill panel's CONTEXT strip. A magic slot injects text the
+#: user did not type, so it must be *shown*; silent injection is how this feature
+#: would lose trust the first time it guessed wrong.
+LABELS: dict[str, str] = {
+    "clipboard": "clipboard",
+    "selection": "selection",
+    "date": "today",
+    "time": "now",
+    "datetime": "now",
+    "app": "app",
+    "window": "window",
+}
+
+
+#: Processes where synthesising Ctrl+C would do harm rather than copy: in a
+#: console it is SIGINT and would kill the user's running command. Selection
+#: capture always skips these, whatever the setting.
+CONSOLE_DENYLIST = frozenset({
+    "windowsterminal.exe", "cmd.exe", "powershell.exe", "pwsh.exe",
+    "conhost.exe", "wt.exe", "mintty.exe", "bash.exe",
+})
+
+
+def is_console(app: str | None) -> bool:
+    return bool(app) and app.strip().lower() in CONSOLE_DENYLIST
+
+
+def is_magic(name: str) -> bool:
+    return name.strip() in RESOLVERS
+
+
+def resolve(name: str, env: ResolveEnv) -> Resolved:
+    """Resolve one magic name against ``env``; unknown names are unavailable."""
+    resolver = RESOLVERS.get(name.strip())
+    if resolver is None:
+        return Resolved(None)
+    try:
+        return resolver(env)
+    except Exception:
+        # A resolver must never take down a paste. Treat any failure as "nothing
+        # here" and fall through to the literal token.
+        return Resolved(None)
+
+
+def make_resolver(env: ResolveEnv) -> Callable[[str], str | None]:
+    """Build the closure :func:`pcc.model.render` calls for each placeholder.
+
+    Returns the resolved text, or ``None`` to mean "not a magic slot / nothing
+    available", on which render keeps its literal-token fallback.
+    """
+
+    def _resolve(name: str) -> str | None:
+        result = resolve(name, env)
+        return result.value if result.available else None
+
+    return _resolve
+
+
+@dataclass
+class ContextItem:
+    """One resolved magic slot, ready to show in the CONTEXT strip."""
+
+    name: str
+    label: str
+    value: str | None
+    pending: bool = False
+
+    @property
+    def available(self) -> bool:
+        return self.value is not None and not self.pending
+
+    def summary(self) -> str:
+        """A compact, safe one-liner: ``clipboard · 1.2k chars`` / ``app · Code.exe``."""
+        if self.pending:
+            return f"{self.label} · …"
+        if self.value is None:
+            return f"{self.label} · —"
+        text = self.value
+        # Long values (a pasted file, a whole selection) are summarised by size
+        # rather than dumped into the strip.
+        if len(text) > 42 or "\n" in text:
+            chars = len(text)
+            size = f"{chars / 1000:.1f}k" if chars >= 1000 else str(chars)
+            return f"{self.label} · {size} chars"
+        return f"{self.label} · {text}"
+
+
+def context_items(names: list[str], env: ResolveEnv) -> list[ContextItem]:
+    """Resolve ``names`` (already known magic) into display items, order kept."""
+    items: list[ContextItem] = []
+    for name in names:
+        result = resolve(name, env)
+        items.append(
+            ContextItem(
+                name=name,
+                label=LABELS.get(name.strip(), name.strip()),
+                value=result.value,
+                pending=result.pending,
+            )
+        )
+    return items

pcc/ipc.py

@@ -0,0 +1,109 @@
+"""Trigger channel: AutoHotkey -> PCC.
+
+AHK posts ``WM_APP`` to a well-known, never-shown top-level window. That is
+roughly a millisecond of work and needs no sockets, no ports, and no polling.
+
+Two details matter and are easy to get wrong:
+
+* The host must be a genuine **top-level** window, not a ``HWND_MESSAGE``-only
+  one -- message-only windows are invisible to AHK's ``WinExist``/``FindWindow``.
+* ``winId()`` must be touched so Qt actually creates the HWND for a widget that
+  is never shown.
+"""
+
+from __future__ import annotations
+
+import ctypes
+from collections.abc import Callable
+from ctypes import wintypes
+
+from PySide6.QtCore import QAbstractNativeEventFilter, Qt
+from PySide6.QtWidgets import QWidget
+
+#: Window title AHK looks for. Must stay in sync with ``scripts/pcc.ahk``.
+HOST_TITLE = "PCC_IPC_HOST"
+
+WM_APP = 0x8000
+#: wParam values, so one message type can carry several commands.
+CMD_SHOW = 0
+CMD_TOGGLE = 1
+CMD_QUIT = 2
+
+
+class _MSG(ctypes.Structure):
+    _fields_ = [
+        ("hwnd", wintypes.HWND),
+        ("message", wintypes.UINT),
+        ("wParam", wintypes.WPARAM),
+        ("lParam", wintypes.LPARAM),
+        ("time", wintypes.DWORD),
+        ("pt_x", wintypes.LONG),
+        ("pt_y", wintypes.LONG),
+    ]
+
+
+class HostWindow(QWidget):
+    """Invisible window whose only job is to own a findable HWND.
+
+    Created *unarmed*: the window exists (so its HWND can be handed to the event
+    filter) but carries a placeholder title, so AHK's ``WinWait`` cannot find it
+    yet. Call :meth:`arm` once the filter is installed. Without this, a trigger
+    arriving in the gap between window creation and filter installation is
+    dispatched to a window that is not yet listening and silently vanishes.
+    """
+
+    UNARMED_TITLE = HOST_TITLE + "_STARTING"
+
+    def __init__(self) -> None:
+        super().__init__(None, Qt.WindowType.Tool)
+        self.setWindowTitle(self.UNARMED_TITLE)
+        self.setObjectName(HOST_TITLE)
+        self.setFixedSize(1, 1)
+        # Force native window creation without ever showing it.
+        self.hwnd = int(self.winId())
+
+    def arm(self) -> None:
+        """Publish the well-known title; from here on AHK can reach us."""
+        self.setWindowTitle(HOST_TITLE)
+
+
+class TriggerFilter(QAbstractNativeEventFilter):
+    """Routes ``WM_APP`` posted at the host window to Python callbacks.
+
+    Runs on Qt's main thread inside the event loop, so handlers may touch the
+    UI directly. Keep them fast -- this sits on the message pump.
+    """
+
+    def __init__(self, hwnd: int, handlers: dict[int, Callable[[], None]]) -> None:
+        super().__init__()
+        self._hwnd = hwnd
+        self._handlers = handlers
+
+    def nativeEventFilter(self, event_type, message):  # noqa: N802 (Qt naming)
+        if event_type != b"windows_generic_MSG":
+            return False, 0
+        try:
+            msg = ctypes.cast(int(message), ctypes.POINTER(_MSG)).contents
+        except (TypeError, ValueError):
+            return False, 0
+
+        if msg.message != WM_APP or int(msg.hwnd or 0) != self._hwnd:
+            return False, 0
+
+        handler = self._handlers.get(int(msg.wParam))
+        if handler is not None:
+            handler()
+        # Swallow it: nothing else has any business seeing this message.
+        return True, 0
+
+
+def find_existing_host() -> int:
+    """HWND of an already-running PCC, or 0.
+
+    Used only for diagnostics; the real single-instance guard is a named mutex,
+    which is race-free where a window search is not.
+    """
+    user32 = ctypes.WinDLL("user32", use_last_error=True)
+    user32.FindWindowW.argtypes = (wintypes.LPCWSTR, wintypes.LPCWSTR)
+    user32.FindWindowW.restype = wintypes.HWND
+    return int(user32.FindWindowW(None, HOST_TITLE) or 0)

pcc/journal.py

@@ -0,0 +1,49 @@
+"""An in-session undo ring for destructive library edits.
+
+Confirmation dialogs are a poor guard: they interrupt every delete to catch the
+rare mistake, and people learn to dismiss them without reading. Undo is both
+faster (no prompt on the common, correct case) and safer (it also recovers the
+delete you *meant*, then regretted). So the palette deletes immediately and
+banks a snapshot here.
+
+Snapshots are whole-library ``to_dict`` dicts. That is coarse, but a library is
+small and correctness beats cleverness: restoring a snapshot cannot leave a
+half-applied edit the way replaying an inverse operation might.
+"""
+
+from __future__ import annotations
+
+import copy
+from dataclasses import dataclass, field
+
+
+@dataclass
+class UndoJournal:
+    """A bounded stack of ``(library_dict, label)`` snapshots, newest last."""
+
+    limit: int = 20
+    _stack: list[tuple[dict, str]] = field(default_factory=list)
+
+    def record(self, library_dict: dict, label: str) -> None:
+        """Snapshot the library *before* a destructive change, tagged ``label``."""
+        self._stack.append((copy.deepcopy(library_dict), label))
+        if len(self._stack) > self.limit:
+            # Drop the oldest; the deep past is not worth unbounded memory.
+            del self._stack[0 : len(self._stack) - self.limit]
+
+    @property
+    def can_undo(self) -> bool:
+        return bool(self._stack)
+
+    @property
+    def next_label(self) -> str | None:
+        return self._stack[-1][1] if self._stack else None
+
+    def undo(self) -> tuple[dict, str] | None:
+        """Pop and return the most recent ``(library_dict, label)``, or ``None``."""
+        if not self._stack:
+            return None
+        return self._stack.pop()
+
+    def __len__(self) -> int:
+        return len(self._stack)

pcc/lint.py

@@ -0,0 +1,102 @@
+"""Library health checks: the only feature that makes a prompt library shrink.
+
+Prompt collections rot silently -- they only ever grow, and nobody schedules a
+cleanup. Surfacing the dead weight (never-used, duplicated, broken, empty) turns
+"organise your library someday" into a concrete, finishable list. Loss aversion,
+used honestly: "you have 14 templates you have never used" prunes what a tidy
+"Manage" button never would.
+
+Pure: a function of the library (and, optionally, usage), returning findings.
+The UI just renders them.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+
+from .model import INCLUDE_PREFIX, PLACEHOLDER_RE, Library
+
+#: Ordering/severity: lower sorts first in the health view.
+SEVERITY = {"broken-include": 0, "empty": 1, "duplicate-title": 2, "untitled": 3, "unused": 4}
+
+
+@dataclass(frozen=True)
+class Finding:
+    kind: str
+    message: str
+    template_id: str
+    tab_name: str
+
+    @property
+    def severity(self) -> int:
+        return SEVERITY.get(self.kind, 99)
+
+
+def _include_refs(body: str) -> list[str]:
+    refs = []
+    for match in PLACEHOLDER_RE.finditer(body):
+        name = match.group(1).strip()
+        if name.startswith(INCLUDE_PREFIX):
+            ref = name[len(INCLUDE_PREFIX):].strip()
+            if ref:
+                refs.append(ref)
+    return refs
+
+
+def lint(library: Library, frecency: Callable[[str], float] | None = None) -> list[Finding]:
+    """Return health findings, most severe first.
+
+    ``frecency`` (from :class:`pcc.usage.UsageStore`) enables the "never used"
+    check; without it that check is skipped, so a fresh install is not scolded
+    for templates it has not had a chance to use yet.
+    """
+    findings: list[Finding] = []
+
+    # Duplicate titles, compared case-insensitively across the whole library.
+    seen: dict[str, int] = {}
+    for _tab, template in library.iter_all():
+        seen[template.title.strip().lower()] = seen.get(template.title.strip().lower(), 0) + 1
+
+    # Valid include targets: any template id or title.
+    valid_refs = set()
+    for _tab, template in library.iter_all():
+        valid_refs.add(template.id)
+        valid_refs.add(template.title.strip().lower())
+
+    for tab, template in library.iter_all():
+        title = template.title.strip()
+
+        if not template.body.strip():
+            findings.append(Finding("empty", "empty body", template.id, tab.name))
+
+        if title.lower() == "untitled" or not title:
+            findings.append(Finding("untitled", "no title", template.id, tab.name))
+
+        if seen.get(title.lower(), 0) > 1:
+            findings.append(
+                Finding("duplicate-title", f"duplicate title “{title}”", template.id, tab.name)
+            )
+
+        for ref in _include_refs(template.body):
+            if ref not in valid_refs and ref.lower() not in valid_refs:
+                findings.append(
+                    Finding("broken-include", f"include “{ref}” not found", template.id, tab.name)
+                )
+
+        if frecency is not None and frecency(template.id) <= 0.0:
+            findings.append(Finding("unused", "never used", template.id, tab.name))
+
+    findings.sort(key=lambda f: (f.severity, f.tab_name))
+    return findings
+
+
+def summary(findings: list[Finding]) -> str:
+    """One-line rollup for a toast, e.g. ``2 broken · 3 unused``."""
+    if not findings:
+        return "library looks healthy"
+    counts: dict[str, int] = {}
+    for finding in findings:
+        counts[finding.kind] = counts.get(finding.kind, 0) + 1
+    order = sorted(counts, key=lambda k: SEVERITY.get(k, 99))
+    return " · ".join(f"{counts[k]} {k.replace('-', ' ')}" for k in order)