@goodandready/dsh-cost-meter 0.7.8 → 0.7.9

package/README.md

@@ -108,14 +108,20 @@ dsh-cost-meter:
 
 ### Configuration Parameters
 
-| Parameter | Type | Default | Description |
-|:---|:---|:---|:---|
-| `currency` | `string` | `"$"` | Display currency symbol or code |
-| `usdRate` | `number` | `1.0` | Exchange rate multiplier from USD |
-| `displayTimeZone` | `string` | `"UTC"` | Timezone for window schedule formatting (e.g. `Europe/London`, `Asia/Shanghai`) |
-| `useOpenRouter` | `boolean` | `true` | Fetch OpenRouter public catalog for fallback models |
-| `prices` | `object` | `{}` | Custom override rates per 1M tokens `{ prompt, completion, cacheRead?, cacheWrite? }` |
-| `modelMap` | `object` | `{}` | Model alias mappings `{ "alias": "target-model" }` |
+| Parameter | Scope / Location | Type | Default | Description |
+|:---|:---|:---|:---|:---|
+| `currency` | GUI / `settings.yaml` | `string` | `"$"` | Display currency symbol (e.g. `$`, `₽`, `€`) |
+| `usdRate` | GUI / `settings.yaml` | `number` | `1.0` | Exchange rate multiplier: units of currency per 1 USD |
+| `displayTimeZone` | GUI / `settings.yaml` | `string` | `"Europe/Moscow"` | IANA timezone for peak/off-peak windows formatting |
+| `useOpenRouter` | GUI / `settings.yaml` | `boolean` | `true` | Automatically fetch rates & discount windows from OpenRouter |
+| `refreshHours` | GUI / `settings.yaml` | `number` | `24` | Hours between periodic OpenRouter catalog updates |
+| `deepseekPeakPrices` | `settings.yaml` only | `object` | `{}` | Override built-in DeepSeek peak rates by model id |
+| `prices` | `settings.yaml` only | `object` | `{}` | Manual rates per 1M tokens `{ input, output, cacheHit?, cacheWrite? }` |
+| `modelMap` | `settings.yaml` only | `object` | `{}` | Route override: `"provider/model"` -> OpenRouter model id |
+| `manualPeakWindowsUtc` | `settings.yaml` only | `array` | `[]` | Manual peak windows HH:MM-HH:MM UTC used with manual prices |
+| `manualOffPeakMultiplier` | `settings.yaml` only | `number` | `1.0` | Multiplier applied outside manual peak windows |
+
+> **Note on GUI vs YAML**: Primary scalar parameters (`currency`, `usdRate`, `displayTimeZone`, `useOpenRouter`, `refreshHours`) are directly editable in the GUI Settings Card under **Settings → Plugins → Plugin Settings → Cost Meter**. Advanced structured rules (`prices`, `modelMap`, `deepseekPeakPrices`, `manualPeakWindowsUtc`, `manualOffPeakMultiplier`) are configured in `settings.yaml` due to their complex dictionary/array schema.
 
 ---
 

package/docs/README.ru.md

@@ -108,14 +108,20 @@ dsh-cost-meter:
 
 ### Параметры конфигурации
 
-| Параметр | Тип | По умолчанию | Описание |
-|:---|:---|:---|:---|
-| `currency` | `string` | `"₽"` | Символ или код валюты для отображения |
-| `usdRate` | `number` | `90.0` | Множитель пересчёта долларовых цен в валюту отображения |
-| `displayTimeZone` | `string` | `"UTC"` | Таймзона для отображения окон в панели |
-| `useOpenRouter` | `boolean` | `true` | Загружать ли каталог цен OpenRouter для сторонних моделей |
-| `prices` | `object` | `{}` | Ручные ставки за 1M токенов `{ prompt, completion, cacheRead?, cacheWrite? }` |
-| `modelMap` | `object` | `{}` | Алиасы моделей `{ "alias": "target-model" }` |
+| Параметр | Доступность | Тип | По умолчанию | Описание |
+|:---|:---|:---|:---|:---|
+| `currency` | GUI / `settings.yaml` | `string` | `"₽"` | Символ валюты в интерфейсе (например, `₽`, `$`, `€`) |
+| `usdRate` | GUI / `settings.yaml` | `number` | `80.0` | Курс обмена: единиц валюты за 1 USD |
+| `displayTimeZone` | GUI / `settings.yaml` | `string` | `"Europe/Moscow"` | IANA часовой пояс для отображения окон пика и не-пика |
+| `useOpenRouter` | GUI / `settings.yaml` | `boolean` | `true` | Загружать ли каталог тарифов и скидочных окон OpenRouter |
+| `refreshHours` | GUI / `settings.yaml` | `number` | `24` | Частота обновления каталога OpenRouter (в часах) |
+| `deepseekPeakPrices` | Только `settings.yaml` | `object` | `{}` | Переопределение встроенных пиковых ставок DeepSeek по id модели |
+| `prices` | Только `settings.yaml` | `object` | `{}` | Ручные ставки за 1M токенов `{ input, output, cacheHit?, cacheWrite? }` |
+| `modelMap` | Только `settings.yaml` | `object` | `{}` | Сопоставление маршрута `"provider/model"` на id в OpenRouter |
+| `manualPeakWindowsUtc` | Только `settings.yaml` | `array` | `[]` | Ручные окна пика HH:MM-HH:MM UTC для ручных ставок |
+| `manualOffPeakMultiplier` | Только `settings.yaml` | `number` | `1.0` | Коэффициент тарифа вне ручных окон пика |
+
+> **Интерфейс настроек (GUI) vs settings.yaml**: Основные параметры (`currency`, `usdRate`, `displayTimeZone`, `useOpenRouter`, `refreshHours`) настраиваются прямо в карточке интерфейса DSH (**Настройки → Плагины → Настройки плагинов → Cost Meter**). Расширенные структурированные правила сопоставления и ручных тарифов задаются через `settings.yaml` из-за сложной древовидной структуры.
 
 ---
 

package/docs/design/DESIGN.md

@@ -82,7 +82,7 @@
   - Не допускать утечек локальных путей и инфраструктурных данных в коде или документации.
 
 ## History & Decisions
-- 2026-09-05 (v0.7.8):
+- 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):

package/docs/plans/findings.md

@@ -1,10 +1,22 @@
-# Findings & Architecture Decisions (v0.7.8)
+# Technical Findings (Issue #21)
 
-## 1. Browser Request Race Conditions
-In `CostMeter`, rapid model switches or toggling the popover calls `load(usedKeys)`. Since network latency varies, an older request might resolve after a newer one. By tracking an active request counter or cancellation token per effect invocation, we ensure only the most up-to-date state response mutates the component state.
+## 1. Config Fields Breakdown
+The plugin `Config` defines 10 fields:
+1. `currency` (string, default '$') -> Present in UI
+2. `usdRate` (number, default 1) -> Present in UI
+3. `displayTimeZone` (string, default 'Europe/Moscow') -> Present in UI
+4. `useOpenRouter` (boolean, default true) -> Missing in UI -> To be added as a checkbox in `CostMeterCard`
+5. `refreshHours` (number, default 24) -> Missing in UI -> To be added as a numeric input in `CostMeterCard`
+6. `modelMap` (dict of string -> string) -> Advanced JSON/YAML route mapping
+7. `prices` (dict of PriceRow) -> Advanced manual pricing rules
+8. `deepseekPeakPrices` (dict of PriceRow) -> Advanced DeepSeek peak overrides
+9. `manualPeakWindowsUtc` (array of string) -> Advanced manual time windows
+10. `manualOffPeakMultiplier` (number) -> Advanced discount multiplier for manual rates
 
-## 2. IANA TimeZone Validation
-`Intl.DateTimeFormat(undefined, { timeZone })` throws a `RangeError` if the timezone string is invalid. We can safely leverage this in `CostMeterCard` to reject typos (e.g. `Europe/Moskow` instead of `Europe/Moscow`) on the client before writing to `settingsScope`.
+By adding `useOpenRouter` and `refreshHours` to `CostMeterCard`, all 5 primary scalar/control settings are directly configurable in the DSH Settings GUI. The 5 advanced structured override rules (`prices`, `modelMap`, `deepseekPeakPrices`, `manualPeakWindowsUtc`, `manualOffPeakMultiplier`) are explicitly documented in README.md and DESIGN.md as YAML configuration rows.
 
-## 3. Query Parameter Sanitization
-The endpoint `GET /dsh-cost-meter/state?models=...` accepts comma-separated model keys. Adding a length bound (e.g. <= 128 chars) and trimming ensures no malformed payloads cause unexpected overhead.
+## 2. Service Access Pattern
+In `lib/index.js`, we have:
+`const settings = ctx.get('settings')` (canonical).
+In `lib/client.js`, `ctx.settingsScope` is accessed directly. We should safely check `(ctx.get && ctx.get('settingsScope')) || ctx.settingsScope || (ctx.services && ctx.services.settingsScope)`.
+Same for `ctx.locale` and `ctx.slots`.

package/docs/plans/progress.md

@@ -1,17 +1,17 @@
-# Implementation Progress (v0.7.8)
+# Progress Log (Issue #21 / v0.7.9)
 
-- [x] Create Gitea Issue #19
-- [x] Create isolated worktree `stability-v078`
-- [x] Bump version to 0.7.8 in `package.json`
-- [x] Add monotonic request sequence guard in `lib/client.js` `CostMeter`
-- [x] Add IANA time zone validation in `lib/client.js` `CostMeterCard`
-- [x] Sanitize query parameters in `lib/index.js`
-- [x] Add automated unit tests (`test/timezone-sanitization.test.mjs`, 11/11 passing)
-- [x] Update design documentation in `docs/design/DESIGN.md`
+- [x] Analyze Issue #21
+- [x] Create worktree `.worktrees/issue-21`
+- [x] Initialize plans (`task_plan.md`, `findings.md`, `progress.md`)
+- [x] Bump version to 0.7.9 in `package.json`
+- [x] Implement settings card additions (`useOpenRouter`, `refreshHours`) in `lib/client.js`
+- [x] Safe service resolution with `ctx.get('...')` in `lib/client.js`
+- [x] Update documentation with full 10-field matrix (`README.md`, `docs/README.ru.md`, `docs/design/DESIGN.md`)
+- [x] Add regression test `test/settings-card-fields.test.mjs` (12/12 passing)
 - [ ] Commit changes with conventional commits (`git-antigravity`)
 - [ ] Create Pull Request and merge into `main`
 - [ ] Test package on MiniPC isolated test server (`192.168.1.123:3082`)
 - [ ] Smoke-test package on production candidate (`192.168.1.111:3080`)
-- [ ] Publish v0.7.8 to npm and GitHub Release
-- [ ] Install v0.7.8 from npm on MiniAI and verify live health
-- [ ] Close Gitea Issue #19 and clean up worktree
+- [ ] Publish v0.7.9 to npm and GitHub Release
+- [ ] Install v0.7.9 from npm on MiniAI and verify live health
+- [ ] Close Gitea Issue #21 and clean up worktree

package/docs/plans/task_plan.md

@@ -1,24 +1,32 @@
-# Task Plan: Stability, Race Condition Prevention & TimeZone Validation (v0.7.8)
+# Task Plan: Address Issue #21 (Settings Card Schema Fields & Service Access)
 
 ## 1. Goal
-Strengthen `@goodandready/dsh-cost-meter` runtime resilience:
-- Prevent race condition response overwrites in browser `CostMeter` component.
-- Validate IANA TimeZone inputs in `CostMeterCard` settings before saving.
-- Sanitize `models` query parameter keys in `lib/index.js` route handler.
-- Maintain strict backward compatibility, zero regression in automated tests.
+Fulfill Gitea Issue #21 requirements:
+1. **Schema Fields Availability in Settings Card**:
+   - Audit all 10 fields of `Config`:
+     - UI fields: `currency`, `usdRate`, `displayTimeZone`.
+     - Boolean toggle: `useOpenRouter` (checkbox / toggle in settings card).
+     - Numeric: `refreshHours` (catalog refresh frequency, e.g. 24 hours).
+     - Complex structured overrides: `prices` (dict), `modelMap` (dict), `deepseekPeakPrices` (dict), `manualPeakWindowsUtc` (array), `manualOffPeakMultiplier` (number).
+     - Add `useOpenRouter` and `refreshHours` directly to the `CostMeterCard` form so all scalar/toggle configuration is editable in GUI.
+     - Document structured dict/array fields (`prices`, `modelMap`, `deepseekPeakPrices`, `manualPeakWindowsUtc`, `manualOffPeakMultiplier`) in documentation, READMEs and DESIGN.md as YAML-only/advanced configuration rows.
+2. **Context Service Access Hygiene**:
+   - Inspect all `ctx.settings` / `ctx.settingsScope` / `ctx.locale` / `ctx.webServer` calls.
+   - Use `ctx.get('...')` or inject where appropriate, or guard against undefined proxiable properties.
+3. **Locale & Translations**:
+   - Provide clean English locale strings as canonical with ru dictionaries, and hint descriptions for all new fields.
 
 ## 2. Checklist
-- [ ] Bump version to `0.7.8` in `package.json`
-- [ ] Implement cancellation flag / abort protection in `lib/client.js` `CostMeter`
-- [ ] Implement `isValidTimeZone` helper and validation check in `CostMeterCard`
-- [ ] Implement key sanitization (length <= 128 chars, alphanumeric/dash/slash) in `lib/index.js`
-- [ ] Add unit tests for timezone check and query sanitization
-- [ ] Run test suite (`npm test`)
-- [ ] Update `docs/design/DESIGN.md`
-- [ ] Conventional Commit & Push
-- [ ] Gitea PR & Merge to `main`
+- [ ] Bump version to 0.7.9 in `package.json`
+- [ ] Add `useOpenRouter` and `refreshHours` fields to `CostMeterCard` in `lib/client.js`
+- [ ] Update `en` and `ru` dictionaries for new fields
+- [ ] Audit and refine service accesses in `lib/index.js` and `lib/client.js`
+- [ ] Update `README.md`, `docs/README.ru.md`, `docs/README.zh.md`, and `docs/design/DESIGN.md`
+- [ ] Add unit test verifying settings card field contract
+- [ ] Run `npm test` (all tests passing)
+- [ ] Conventional commit & push
+- [ ] Gitea PR & merge
 - [ ] Test on MiniPC test server (`192.168.1.123`)
-- [ ] Production Smoke Verification on MiniAI (`192.168.1.111`)
-- [ ] Publish Tag `v0.7.8`, GitHub Release & npm
-- [ ] Update production profile from npm
-- [ ] Close Gitea Issue #19 and clean up worktree
+- [ ] Install on production MiniAI (`192.168.1.111`) & verify
+- [ ] Release v0.7.9 on GitHub & npm
+- [ ] Close Issue #21 & cleanup worktree

package/lib/client.js

@@ -49,6 +49,10 @@ window.__ModuleLoader__.load({
       'hint.currency': 'Currency symbol shown in the widget (e.g. $, ₽, €).',
       'hint.usdRate': 'Exchange rate: units of currency per 1 USD (e.g. 80 for ₽).',
       'hint.displayTimeZone': 'IANA timezone used for tariff peak/off-peak schedule.',
+      'field.useOpenRouter': 'Use OpenRouter Catalog',
+      'hint.useOpenRouter': 'Pull rates and discount windows automatically from the OpenRouter catalog.',
+      'field.refreshHours': 'Catalog Refresh Interval (hours)',
+      'hint.refreshHours': 'How often to fetch fresh model rates from OpenRouter (default: 24).',
     }
 
     const ru = {
@@ -79,6 +83,10 @@ window.__ModuleLoader__.load({
       'hint.currency': 'Символ валюты, отображаемый в виджете (например, ₽, $, €).',
       'hint.usdRate': 'Сколько единиц валюты в 1 долларе США (например, 80 для ₽).',
       'hint.displayTimeZone': 'IANA таймзона для расчёта часов пика и не-пика (например, Europe/Moscow).',
+      'field.useOpenRouter': 'Каталог OpenRouter',
+      'hint.useOpenRouter': 'Автоматически загружать тарифы и скидочные окна из каталога OpenRouter.',
+      'field.refreshHours': 'Интервал обновления каталога (часы)',
+      'hint.refreshHours': 'Как часто обновлять ставки из OpenRouter (по умолчанию: 24).',
     }
 
     let ChevronIcon = null
@@ -118,6 +126,8 @@ window.__ModuleLoader__.load({
       '.dcm-sub { color:var(--dsw-alias-label-secondary); font-size:13px } ' +
       '.dcm-body { border-top:1px solid var(--dsw-alias-border-l2); margin:0 16px; padding-bottom:8px } ' +
       '.dcm-field { display:flex; flex-direction:column; gap:6px; padding:12px 0 } ' +
+      '.dcm-row-check { display:flex; align-items:center; gap:8px; padding:12px 0 } ' +
+      '.dcm-check { width:16px; height:16px; accent-color:var(--dsw-alias-brand-primary, #6366f1); cursor:pointer } ' +
       '.dcm-label { color:var(--dsw-alias-label-primary); font-size:13px; font-weight:500 } ' +
       '.dcm-hint { color:var(--dsw-alias-label-secondary); font-size:12px } ' +
       '.dcm-input { height:34px; border:1px solid var(--dsw-alias-border-l2); background:var(--dsw-alias-bg-layer-3); color:var(--dsw-alias-label-primary); border-radius:8px; padding:0 12px; font-size:13px } ' +
@@ -149,9 +159,10 @@ window.__ModuleLoader__.load({
     }
 
     function useActiveLocale(ctx) {
+      const localeService = (ctx && typeof ctx.get === 'function' ? ctx.get('locale') : null) || (ctx && ctx.locale) || (ctx && ctx.services && ctx.services.locale)
       return React.useSyncExternalStore(
-        React.useMemo(() => (cb) => (ctx && ctx.locale ? ctx.locale.subscribe(cb) : () => {}), [ctx]),
-        React.useCallback(() => (ctx && ctx.locale && ctx.locale.getSnapshot ? ctx.locale.getSnapshot().active : 'ru'), [ctx]),
+        React.useMemo(() => (cb) => (localeService && typeof localeService.subscribe === 'function' ? localeService.subscribe(cb) : () => {}), [localeService]),
+        React.useCallback(() => (localeService && typeof localeService.getSnapshot === 'function' ? localeService.getSnapshot().active : 'ru'), [localeService]),
         React.useCallback(() => 'ru', []),
       )
     }
@@ -166,9 +177,10 @@ window.__ModuleLoader__.load({
       const [err, setErr] = React.useState('')
       const [saved, setSaved] = React.useState(false)
 
+      const settingsScope = (ctx && typeof ctx.get === 'function' ? ctx.get('settingsScope') : null) || (ctx && ctx.settingsScope) || (ctx && ctx.services && ctx.services.settingsScope)
       const scope = React.useMemo(
-        () => (ctx && ctx.settingsScope ? ctx.settingsScope.bind({ namespace: NS }) : undefined),
-        [ctx],
+        () => (settingsScope ? settingsScope.bind({ namespace: NS }) : undefined),
+        [settingsScope],
       )
 
       const snapshot = React.useSyncExternalStore(
@@ -188,6 +200,8 @@ window.__ModuleLoader__.load({
             currency: stored.currency !== undefined ? String(stored.currency) : '$',
             usdRate: stored.usdRate !== undefined ? String(stored.usdRate) : '1',
             displayTimeZone: stored.displayTimeZone !== undefined ? String(stored.displayTimeZone) : 'Europe/Moscow',
+            useOpenRouter: stored.useOpenRouter !== undefined ? Boolean(stored.useOpenRouter) : true,
+            refreshHours: stored.refreshHours !== undefined ? String(stored.refreshHours) : '24',
           })
         }
       }, [status, stored, draft])
@@ -218,6 +232,19 @@ window.__ModuleLoader__.load({
           } catch (e) { broken.push('displayTimeZone: ' + (e && e.message || String(e))) }
         }
 
+        try {
+          await scope.set('useOpenRouter', Boolean(draft.useOpenRouter))
+        } catch (e) { broken.push('useOpenRouter: ' + (e && e.message || String(e))) }
+
+        const hoursNum = Number(String(draft.refreshHours).trim())
+        if (!Number.isFinite(hoursNum) || hoursNum <= 0) {
+          broken.push('refreshHours: must be a positive number')
+        } else {
+          try {
+            await scope.set('refreshHours', hoursNum)
+          } catch (e) { broken.push('refreshHours: ' + (e && e.message || String(e))) }
+        }
+
         setSaving(false)
         if (broken.length) {
           setErr(t('settings.saveFailed') + broken.join('; '))
@@ -273,6 +300,28 @@ window.__ModuleLoader__.load({
                     }),
                     React.createElement('span', { className: 'dcm-hint' }, t('hint.displayTimeZone')),
                   ),
+                  React.createElement('div', { className: 'dcm-row-check' },
+                    React.createElement('input', {
+                      id: 'dcm-use-openrouter',
+                      type: 'checkbox',
+                      className: 'dcm-check',
+                      checked: draft ? Boolean(draft.useOpenRouter) : true,
+                      onChange: (e) => setDraft({ ...draft, useOpenRouter: e.target.checked }),
+                    }),
+                    React.createElement('label', { htmlFor: 'dcm-use-openrouter', className: 'dcm-label', style: { cursor: 'pointer' } }, t('field.useOpenRouter')),
+                  ),
+                  React.createElement('span', { className: 'dcm-hint', style: { marginTop: -4, display: 'block', paddingBottom: 10 } }, t('hint.useOpenRouter')),
+                  React.createElement('div', { className: 'dcm-field' },
+                    React.createElement('label', { className: 'dcm-label' }, t('field.refreshHours')),
+                    React.createElement('input', {
+                      className: 'dcm-input',
+                      type: 'number',
+                      step: 'any',
+                      value: (draft && draft.refreshHours) !== undefined ? draft.refreshHours : '',
+                      onChange: (e) => setDraft({ ...draft, refreshHours: e.target.value }),
+                    }),
+                    React.createElement('span', { className: 'dcm-hint' }, t('hint.refreshHours')),
+                  ),
                   err ? React.createElement('div', { className: 'dcm-msg-err', style: { padding: '4px 0' } }, err) : null,
                   saved ? React.createElement('div', { className: 'dcm-msg-ok', style: { padding: '4px 0' } }, t('settings.saved')) : null,
                   React.createElement('div', { className: 'dcm-foot' },
@@ -487,7 +536,7 @@ window.__ModuleLoader__.load({
       const [open, setOpen] = React.useState(false)
       const [now, setNow] = React.useState(() => new Date())
       const box = React.useRef(null)
-      const settingsScope = ctx.settingsScope || (ctx.services && ctx.services.settingsScope)
+      const settingsScope = (ctx && typeof ctx.get === 'function' ? ctx.get('settingsScope') : null) || (ctx && ctx.settingsScope) || (ctx && ctx.services && ctx.services.settingsScope)
       const settingsSnap = React.useSyncExternalStore
         ? React.useSyncExternalStore(
             (cb) => (settingsScope && typeof settingsScope.subscribe === 'function' ? settingsScope.subscribe(cb) : () => {}),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-cost-meter",
-  "version": "0.7.8",
+  "version": "0.7.9",
   "description": "DeepSeek Harness plugin: a session cost chip in the conversation header - live token usage by bucket, peak/off-peak tariff, and a countdown to the next tariff switch.",
   "type": "module",
   "main": "lib/index.js",