@goodandready/dsh-cost-meter 0.8.2 → 0.8.4

package/docs/design/DESIGN.md

@@ -1,117 +0,0 @@
-# DESIGN.md — dsh-cost-meter
-
-## Product / Purpose
-- Назначение: Отображение стоимости активной сессии диалога в реальном времени, тарифов (пик / не-пик / единый) за 1M токенов, обратного отсчёта до смены окна, прозрачной детализации расходов по каждой задействованной модели и нативного управления конфигурацией плагина.
-- Аудитория: Пользователи и инженеры DeepSeek Harness, контролирующие потребление токенов и бюджет на LLM-провайдеров.
-- Статус: Активная публичная поставка (@goodandready/dsh-cost-meter).
-
-## User Surfaces
-- Web/UI:
-  - Компактный чип в слоте `conversation.session.header.utilities` (order: 10).
-  - Выпадающая панель детализации (width: 320px, absolute positioning, click-outside dismissal).
-  - Карточка настроек плагина в `settings.plugin.item` (слот `settings.plugin.item` с fallback на `settings.section`).
-- DSH UI / settings / slots:
-  - Слот чипа: `conversation.session.header.utilities`.
-  - Слот карточки настроек: `settings.plugin.item`.
-  - Настройки: реестр DSH `settings.register("dsh-cost-meter", Config)` (валюта `currency`, множитель курса `usdRate`, таймзона `displayTimeZone`, опрос OpenRouter `useOpenRouter`, ручные ставки `prices`, сопоставление `modelMap`).
-  - Локализация: регистрация словарей через `ctx.locale.register("dsh-cost-meter", { en, ru })` с поддержкой переключения языков через `useActiveLocale(ctx)`.
-- API:
-  - HTTP `GET /dsh-cost-meter/state` (параметр `?models=...` для получения тарифов по задействованным моделям).
-- CLI:
-  - Управление через CLI харнесса: `dsh plugin --profile web add @goodandready/dsh-cost-meter`.
-- Документация:
-  - README.md, index.md, docs/testing/public-route.md, docs/testing/projection-lifecycle.md, docs/deployment/public-release.md.
-
-## Visual Direction (Unified with dsh-clinebot)
-- Атмосфера: Строгий утилитарный нативный интерфейс DSH, высокая информационная плотность без визуального шума.
-- Утверждённые референсы: Эталонный плагин `@goodandready/dsh-clinebot`, дизайн-система DeepSeek Harness (`--dsw-alias-*`), карточки секций `.dcm-section-card`, бейджи статуса `.dcm-badge`, адаптивная сетка параметров `.dcm-grid-2`, чипы в шапке сессии.
-- Отказоустойчивость: Обязательный `ErrorBoundary` вокруг карточки настроек и поповера шапки (предотвращает исчезновение слотов ядра при исключениях рендеринга).
-- Синхронизация зеркал: `refreshMirrorUntilVisible(ctx)` для надёжного доступа к зеркалу `settingsScope`.
-- Атмосфера: Строгий утилитарный нативный интерфейс DSH, высокая информационная плотность без визуального шума.
-- Утверждённые референсы: Дизайн-система DeepSeek Harness (`--dsw-alias-*`), чипы в шапке сессии (`dsh-key-rotation`, `dsh-context-lens`), стандарт карточек настроек DSH.
-- Не копировать: Избыточные градиенты, внешние модальные окна, тяжелые тени, кастомные несогласованные шрифты.
-
-## Foundations
-- Цвета и роли:
-  - `--dsw-alias-label-primary`: основной текст, заголовки, суммы.
-  - `--dsw-alias-label-tertiary`: второстепенные пояснения, метки столбцов, чип без тарифа.
-  - `--dsw-alias-border-l2`: разделители секций и обводка панели.
-  - `--dsw-alias-bg-layer-2` / `--dsw-alias-bg-base`: подложка всплывающей панели и карточки настроек.
-  - `--dsw-alias-state-success-primary` / `--dsw-alias-state-success-tertiary`: подсветка льготного окна (не-пик).
-  - `--dsw-alias-state-warn-primary` / `--dsw-alias-state-warn-tertiary`: подсветка полного тарифа (пик).
-- Типографика:
-  - Системный стек шрифтов DSH, размер 12px, интерлиньяж 1.5.
-  - Обязательно `fontVariantNumeric: "tabular-nums"` для всех числовых колонок, токенов и таймеров.
-- Сетка и отступы:
-  - Чип: высота 22px, padding: 0 8px, gap: 6px, border-radius: 6px.
-  - Панель: padding: 12px 14px, border-radius: 10px, ширина 320px.
-  - Карточка настроек: нативный складной контейнер (`.dcm-card`) с шапкой, статусами-бейджами (`dcm-badge-ok`, `dcm-badge-warn`, `dcm-badge-bad`), 3 структурированными секциями (`Основные параметры`, `Каталог OpenRouter`, `Диагностика и статус`), защитой ввода и кнопкой сохранения (`dcm-btn-primary`).
-
-## Components & States
-- Чип:
-  - `Unknown Tariff`: отображает «тариф ?» в приглушённом цвете `label-tertiary`.
-  - `Flat Tariff`: фон `--dsw-alias-state-warn-tertiary`, текст `--dsw-alias-state-warn-primary`, заголовок «Единый тариф».
-  - `Off-Peak`: зелёная плашка успеха (льготный тариф).
-  - `Peak`: оранжевая плашка предупреждения (полный тариф).
-  - Таймер: время до смены тарифа с пониженной непрозрачностью (`opacity: 0.75`).
-- Панель:
-  - Заголовок с текущей моделью и статусом окна.
-  - Сетка тарифов за 1M токенов (не-пик / пик / единая ставка).
-  - Блок «Из чего сложилась сумма»:
-    - Список всех моделей сессии с токенами и суммарной стоимостью.
-    - Для модели без тарифа отображается статус `не указана стоимость` (`rate_unspecified`).
-  - Итог сессии: `Сессия: ≈ <валюта><сумма>`.
-  - Отсутствие мусорных служебных плашек (строка источника OpenRouter исключена).
-- Карточка настроек (`CostMeterCard`):
-  - Сворачиваемый заголовок с шевроном и иконкой счётчика.
-  - Статус снимка: `ready` (зелёный бейдж), `loading` (нейтральный), `unavailable` (серый).
-  - Поля: выбор символа валюты (`currency`), курс к USD (`usdRate`), таймзона отображения (`displayTimeZone`).
-  - Локализованные лейблы и плейсхолдеры на русском и английском языках.
-
-## User Flows
-1. Пользователь ведёт диалог с ассистентом: чип в шапке инкрементально обновляет потраченную сумму прямо во время стриминга ответа ассистента.
-2. Пользователь нажимает на чип: открывается всплывающая панель с тарифной сеткой и расходами по каждой модели сессии.
-3. Если модель не тарифицирована: в списке моделей выводится статус `не указана стоимость`.
-4. Пользователь открывает настройки DSH (`Настройки` -> `Плагины`): карточка `dsh-cost-meter` позволяет изменить валюту, курс и таймзону с мгновенным сохранением в `settingsScope`.
-
-## Do / Don't
-- Do:
-  - Использовать CSS-переменные DSH для согласованности с тёмной и светлой темами.
-  - Всегда разделять расходы по задействованным моделям.
-  - Использовать табличные цифры (`tabular-nums`) для предотвращения дёргания вёрстки при стриме.
-  - Использовать `ctx.locale.register` и `useActiveLocale` для всех строк интерфейса.
-- Don't:
-  - Не выводить техническую служебную информацию о каталоге OpenRouter в интерфейс пользователя.
-  - Не заменять отсутствие тарифа обманчивым нулём или невнятным прочерком — писать прямо `не указана стоимость`.
-  - Не допускать утечек локальных путей и инфраструктурных данных в коде или документации.
-
-## History & Decisions
-- 2026-09-13 (v0.8.2):
-  - Приведение к стандарту локализации DSH (dsh-plugin-authoring): английский (en) — исходный и fallback-язык, китайский (zh) — обязательная пользовательская локаль. Русский словарь вынесен из плагина; все строки для русского интерфейса переданы в goodandready/dsh-russian-lang.
-  - Нативный точечный dot-индикатор статуса чипа в шапке (.dcm-dot): зеленый (off-peak), янтарный (peak), красный пульсирующий (budget exceeded), серый (idle/unknown).
-  - Адаптивное скрытие таймера чипа на экранах < 680px при сохранении суммы расхода.
-  - Расчёт и отображение выгоды от контекстного кэша (Cache Savings): строка 'Cache saved: ≈ $X.XX (-Y%)' при наличии cacheReadTokens.
-  - Компактный список моделей с аккордеоном при 3+ задействованных моделях сессии.
-- 2026-09-12 (v0.8.1):
-  - Оптимизация производительности расчёта тарифов: замена 1440-минутного цикла на алгоритм O(K) по точкам перехода и мемоизация экстремумов через WeakMap.
-  - Серверный кэш разрешения тарифов resolveTariffCache (Map) с автоматической очисткой при обновлении каталога.
-  - Поддержка ETag и ответа 304 Not Modified на эндпоинте /dsh-cost-meter/state.
-  - Кнопка ручной синхронизации каталога цен в секции OpenRouter с защитой от флуда (cooldown 30 сек).
-  - Интеллектуальные подсказки экономии: плашка скорого наступления льготного тарифа (скидка 50%) и отсчёт времени.
-  - Поддержка настраиваемого порога бюджета сессии (budgetThreshold) с предупреждающей подсветкой чипа.
-  - Кнопка быстрого копирования текстового отчёта о расходах в буфер обмена.
-  - Таблица нормализации алиасов вендоров (z-ai -> zai, deepseek-official -> deepseek, gemini -> google).
-- 2026-09-05 (v0.7.9):
-  - Hotfix: исправлен ReferenceError (t is not defined) в объекте словаря ru (lib/client.js) (#15).
-  - Добавлен автоматический тест на чистое исполнение фабрики client loader (`test/public-route.test.mjs`).
-- 2026-09-05 (v0.7.4):
-  - Добавлена нативная карточка настроек в слот `settings.plugin.item` (`#12`).
-  - Реализована полная локализация клиентской части через `ctx.locale.register` (`#2`).
-  - Реализовано provider-aware разрешение тарифов OpenRouter vs DeepSeek (`#3`).
-  - Добавлены всеобъемлющие регрессионные тесты на проекцию и сопоставление (`test/projection-lifecycle.test.mjs`, `#1`).
-  - Закрыт issue о согласовании публичного scope пакета (`#13`).
-- 2026-09-05 (v0.7.3):
-  - Удалена строка источника цен OpenRouter.
-  - Список моделей в блоке «Из чего сложилась сумма» унифицирован и отображается для всех задействованных моделей сессии.
-  - Для нетарифицированных моделей введён явный статус «не указана стоимость».
-  - Пакет переведён на публичный scope `@goodandready/dsh-cost-meter`.

package/docs/plans/findings.md

@@ -1,13 +0,0 @@
-# Findings: Issue #27 (v0.8.2)
-
-## 1. Точечный индикатор статуса
-- Сплошной яркий фон чипа в тулбаре DSH перетягивает на себя внимание от основного чата.
-- Нативный паттерн DSH: нейтральный полупрозрачный фон с цветной точкой (dot indicator 6x6px) и моноширинным текстом `tabular-nums`.
-
-## 2. Экономия кэша (Cache Savings)
-- При использовании кэша провайдера (DeepSeek, Claude, Gemini) стоимость `cacheReadTokens` значительно ниже `uncachedInputTokens` (у DeepSeek: $0.014 vs $0.14-$0.44 за 1M токенов).
-- Разница между стоимостью токенов без кэша (`cacheReadTokens * inputRate`) и фактической стоимостью (`cacheReadTokens * cacheHitRate`) наглядно демонстрирует реальную экономию пользователя прямо в поповере.
-
-## 3. Стандарт локализации
-- По стандарту DSH (`dsh-plugin-authoring`, `dhs-plugin-release-workflow`), плагин обязан иметь `en` как канонический исходный и `zh` как обязательную локаль.
-- Русский перевод не зашивается в плагин, а поставляется через отдельный плагин `dsh-russian-lang`. Для синхронизации перевода открывается issue в репозитории `goodandready/dsh-russian-lang`.

package/docs/plans/progress.md

@@ -1,12 +0,0 @@
-# Progress: Issue #27 (v0.8.2)
-
-- **2026-09-13 15:06**:
-  - Создана Gitea Issue #27.
-  - Развернут worktree `.worktrees/issue-27` на ветке `feat/issue-27-ui-and-locales`.
-  - Зафиксированы планы и стандарты в `docs/plans/`.
-
-- **2026-09-13 15:08**:
-  - Реализованы улучшения в `lib/client.js` (dot status indicator, cache savings display, multi-model accordion, en/zh locales).
-  - Добавлены тесты в `test/v082-ui-locales.test.mjs` (все 22 теста успешно пройдены).
-  - Версия обновлена до `0.8.2`.
-  - Документация актуализирована на en, zh, ru.

package/docs/plans/task_plan.md

@@ -1,31 +0,0 @@
-# Task Plan: Issue #27 (v0.8.2) — Визуальная индикация шапки/поповера и стандарт локализации en/zh
-
-## Цели
-1. **Визуальные улучшения шапки и поповера**:
-   - Чип в шапке: точечный dot-индикатор (зеленый/янтарный/красный/серый) вместо сплошного фона, аккуратная интеграция с тулбаром DSH.
-   - Адаптивное скрытие таймера на узких экранах, сохранение суммы.
-   - Индикация экономии контекстного кэша (Cache Savings): строка `Cache saved: ≈ $X.XX (-Y%)`.
-   - Компактный список/аккордеон при нескольких моделях сессии (3+ модели).
-   - Точные нативные токены тем DSH.
-2. **Стандарт локализации DSH**:
-   - Исходный и fallback язык: `en`.
-   - Обязательная локаль: `zh` (полный набор эквивалентных ключей).
-   - Исключение зашитого `ru` словаря из плагина.
-   - Создание Issue в `goodandready/dsh-russian-lang` со всеми строками для русского перевода.
-3. **Документация и релиз**:
-   - Версия `0.8.2` (инкремент только `z`).
-   - Актуализация `docs/design/DESIGN.md`, `README.md` (en), `docs/README.zh.md` (zh), `docs/README.ru.md` (ru).
-   - 100% покрытие unit-тестами без внешних зависимостей.
-   - Валидация на test server (`:3082`) и на production (`:3080`).
-   - Запрос подтверждения -> публикация v0.8.2.
-
-## Статус выполнения
-- [x] Issue #27 создана
-- [x] Worktree `.worktrees/issue-27` развернут
-- [x] Реализация `lib/client.js` (UI шапки/поповера, расчет cache savings, словари en/zh)
-- [x] Обновление тестов в `test/`
-- [x] Обновление документации (`DESIGN.md`, `README.md`, `README.zh.md`, `README.ru.md`)
-- [ ] Регистрация Issue в `goodandready/dsh-russian-lang`
-- [ ] Сборка и приёмка кандидата (:3082, :3080)
-- [ ] Публикация релиза v0.8.2
-- [ ] Закрытие Issue #27 и cleanup worktree

package/docs/testing/projection-lifecycle.md

@@ -1,28 +0,0 @@
-# Регрессионное тестирование проекции тарифов и жизненного цикла
-
-Тесты проверяют логику тарификации, парсинг временных окон UTC, сопоставление моделей и provider-aware разрешение ставок.
-
-## Запуск тестов
-
-```bash
-npm test
-```
-
-## Проверяемые сценарии (`test/projection-lifecycle.test.mjs`)
-
-1. **`hhmmToMinutes` и `parseWindow`**:
-   - Корректный разбор диапазонов `HH:MM-HH:MM` в минуты от начала суток UTC.
-   - Граничные условия: переход через полночь (`23:00-02:00`), пустые или невалидные строки.
-
-2. **`slotOf`**:
-   - Вычисление 30-минутного слота суток (`0..47`) на основе переданного timestamp.
-   - Независимость накопления расхода от текущего момента времени (сохранение исторической ставки слота).
-
-3. **`indexCatalog` и `matchModel`**:
-   - Индексация моделей OpenRouter с поддержкой поиска без учета регистра.
-   - Нормализация суффиксов вендоров и версий (например, `vendor/model:variant`).
-
-4. **`resolveTariff` (Provider-aware)**:
-   - Если указан `provider: "openrouter"`, плагин в первую очередь обращается к каталогу OpenRouter, даже если имя модели содержит `deepseek`.
-   - Если провайдер не `openrouter` (или `deepseek`), DeepSeek модели тарифицируются по официальной зашитой сетке (пик / не-пик).
-   - Ручные ставки `prices` из конфигурации имеют высший приоритет над внешними каталогами.

package/docs/testing/public-route.md

@@ -1,12 +0,0 @@
-# Проверка публичного маршрута
-
-1. Выполнить `npm test`.
-2. Проверить `npm pack --dry-run` и отсутствие локальных установочных ссылок,
-   абсолютных infra-путей, IP-адресов и секретов в поставляемых файлах.
-3. Собрать tarball из проверенного Git worktree.
-4. Установить tarball на изолированный тестовый DSH web server (MiniPC).
-5. Для browser half проверить loader id `@goodandready/dsh-cost-meter`, HTTP route
-   состояния `GET /dsh-cost-meter/state` и smoke-сценарий тарификации (список моделей,
-   расчёт стоимости, статус «не указана стоимость»); для host half — bundle identity и host smoke.
-6. Выполнить cleanup тестовой установки и убедиться, что постоянные плагины
-   сохранили работоспособность.