dsh-oauth-login 0.2.4

package/docs/openrouter-sync.md

@@ -0,0 +1,84 @@
+# OpenRouter model sync
+
+## Request and scope
+
+Use the normal DSH OAuth plugin to discover current OpenRouter models and make
+free models easy to select. Preserve the existing two-level composer menu,
+search, reasoning selection, GLM key-input fix and all other providers. Do not
+change DSH core, credentials, existing conversations, or the selected model.
+
+## Runtime contract
+
+- After OpenRouter login: refresh the public Models API immediately.
+- Startup: show the persisted catalog; refresh when older than 15 minutes.
+- While signed in: one Host-owned timer refreshes every 15 minutes. Logout and
+  plugin disposal cancel the timer and in-flight refresh.
+- Opening the menu reads cached metadata and asks for an async stale refresh.
+- Manual refresh is coalesced across windows and has a 60-second cooldown.
+- A network, empty-data or partial-response failure preserves the last-good
+  list and timestamp. Cache lives beside the plugin credential file in
+  .dsh-oauth-openrouter-models.json, with no tokens or keys.
+- New models enter the actual pi-ai-backed DSH adapter, not only the menu.
+- Full live catalogs replace obsolete builtin entries; missing current
+  selections are not silently changed to another model.
+
+## Price and safety contract
+
+The free badge uses official prices, including extra unit costs. Missing or
+invalid prices and conditional pricing overrides are not labelled free.
+The expiration_date field means endpoint deprecation, not a promotion deadline.
+Unknown promotion deadlines are not invented.
+
+Free requests pin the model ID, set all supported provider price caps to zero,
+disable provider/model fallbacks, disable known paid OpenRouter plugins, and
+reject hosted tools or file/audio processing. Ordinary DSH function tools stay
+available. A model previously advertised as free keeps its zero-price guard
+even after a restart or price change. A promotion ending never opts the user
+into a paid call. Explicit paid model variants remain separate choices.
+
+Platform-enforced account/organization plugins can override per-request
+settings. DSH cannot override those policies: users must disable forced paid
+plugins in OpenRouter before relying on free inference. The UI states this
+limit; it does not promise that all account-level services are free.
+
+Official contracts:
+[Models API](https://openrouter.ai/docs/guides/overview/models),
+[price caps](https://openrouter.ai/docs/guides/routing/provider-selection#max-price),
+[plugins](https://openrouter.ai/docs/guides/features/plugins),
+[free router](https://openrouter.ai/docs/guides/routing/routers/free-router).
+
+## Native UI contract
+
+Clarity-first, single-agent implementation. Keep the host's font, compact
+menu density, theme tokens and two-level layout. No new font, imagery,
+animation, dashboard or layout family. The visual cue is a small green
+text badge, never color alone. A stale free badge becomes neutral and says
+it is cached. Model names may truncate; price/safety state must not.
+
+Show All / Free only (OpenRouter), tool capability, context size, last sync,
+refresh feedback and a retry path. The OpenRouter settings card shares the
+same client metadata store. A background update cannot steal keyboard focus
+or change selection. Controls wrap at narrow widths; menu scrolling is
+internal. No token/key values are needed for browser verification.
+
+## OKF decision bindings
+
+| Active concept | Decision | Target | Verification |
+| --- | --- | --- | --- |
+| request-integrity | Normal DSH only; no core or selection mutation | Adapter, menu, deployment | Route tests; exact Host/PID verification |
+| accessibility-usability | Text badges, named controls, stable focus | Filters, refresh, model rows | Keyboard/focus and screen-state tests |
+| responsive-interaction | Wrap status/filters; bounded, scrollable menu | Composer popover | Desktop and narrow screenshots/geometry |
+| state-language | Distinguish cached, stale, refreshing, failed and signed out | Shared sync status | Failure/cooldown tests and visible state review |
+| typography-system | Keep native type; wrap critical status; separate model ID | Model metadata rows | Long-label and mixed Chinese/English rendering |
+
+Support: existing DSH theme/source, web-product/content-model branches,
+visual-verification and quality-gates. A compact feature contract is used
+instead of introducing a separate design system for this existing component.
+
+## Acceptance
+
+Unit checks cover parsing, free classification, cache restart, refresh
+frequency/coalescing, logout races, real adapter resolution, and final outbound
+payload guards. Rendered checks cover search/free filtering, manual refresh,
+cached failure, focus, unchanged selection and narrow layout. dshx check,
+artifact sync and running Host/UI evidence are separate delivery gates.

package/lib/bin.d.ts

@@ -0,0 +1,5 @@
+//#region src/bin.d.ts
+/** Standalone credential CLI. Never reads or writes official CLI auth files. */
+declare function run(argv: readonly string[]): Promise<number>;
+//#endregion
+export { run };