@goodandready/dsh-clinebot 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+All notable changes to `@goodandready/dsh-clinebot` will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2026-09-04
+
+### Added
+- **Dedicated Settings Page**: Added standalone Settings section in DSH (`settings.section`, order 28, menu item **ClineBot**) alongside the compact plugin card (`settings.plugin.item`).
+- **Quota & Usage Limits Dashboard**: Integrated real-time tracking of official ClinePass rolling windows (`GET /users/me/plan/usage-limits`):
+  - 5-hour rolling limit progress bar with countdown to window reset.
+  - Weekly limit progress bar with percentage remaining.
+  - User account email and monthly renewal cycle tracking.
+- **In-UI Secure Key Storage**: Added field to paste API keys directly in the web UI, safely saving into DSH credentials storage (`~/.dsh/.credentials.yaml`) via `ctx.credentials.set(credentialRef(apiKeyEnv), key)`.
+- **Custom Models Manager**: Added UI form to register new ClinePass models (ID, name, context size, Vision support) directly into the catalog without waiting for plugin updates.
+- **Model Picker Management**: Granular checkboxes to enable/disable models exposed to the DSH chat picker, with quick filters ("All", "Vision Only", "Coding", "Recommended").
+- **Slash-Command `/cline`**: Registered chat slash-command showing subscription status, quota progress bars, ping latency, and active model.
+- Extended automated unit test suite (`test/cline-client.test.js`, `test/models.test.js`) with 9 tests covering usage limits, custom models, and credential storage.
+
+## [0.1.0] - 2026-09-04
+
+### Added
+- Initial release of `@goodandready/dsh-clinebot`.
+- Curated static catalogue for 11 official ClinePass open-weights models (`lib/models.js`).
+- Native OpenAI-compatible client wrapper with health probes and latency-measuring smoke chat completions (`lib/cline-client.js`).
+- Cordis service module injecting `settings`, `webServer`, and `credentials` with automatic DSH `llm-pi-ai` provider registration (`lib/index.js`).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GooDAnDReaDY
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,153 @@
+# 📦 @goodandready/dsh-clinebot
+
+<div align="center">
+
+<h3>Native ClineBot / ClinePass Provider Companion for DeepSeek Harness</h3>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@goodandready/dsh-clinebot"><img src="https://img.shields.io/npm/v/@goodandready/dsh-clinebot.svg?style=for-the-badge&color=6366f1&labelColor=1e1b4b" alt="npm version"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/github/license/GooDAnDReaDY/dsh-clinebot.svg?style=for-the-badge&color=10b981&labelColor=064e3b" alt="license"></a>
+  <a href="https://github.com/topics/dsh-plugin"><img src="https://img.shields.io/badge/DSH-Plugin-8b5cf6.svg?style=for-the-badge&labelColor=2e1065" alt="DSH Plugin"></a>
+  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node-20%2B-f59e0b.svg?style=for-the-badge&labelColor=451a03" alt="Node version"></a>
+</p>
+
+<!-- Author Showcase Link -->
+<p align="center">
+  <a href="https://goodandready.app/"><img src="https://img.shields.io/badge/All_Author_Projects-goodandready.app-ff4500.svg?style=for-the-badge&logo=rocket&logoColor=white&labelColor=1a1a2e" alt="All Projects"></a>
+</p>
+
+<p align="center">
+  <a href="README.md"><b>🇬🇧 English</b></a> •
+  <a href="README.ru.md"><b>🇷🇺 Русский</b></a> •
+  <a href="README.zh.md"><b>🇨🇳 中文说明</b></a>
+</p>
+
+</div>
+
+---
+
+## ⚡ Overview & The Problem
+
+**ClinePass** (`https://cline.bot`) is a flat-rate subscription service ($9.99/mo) providing developers with 2–5x higher rate limits across premier open-weights coding and reasoning models through a single OpenAI-compatible endpoint (`https://api.cline.bot/api/v1`).
+
+Integrating ClinePass into DeepSeek Harness (DSH) natively poses key challenges:
+1. **No `/v1/models` Discovery**: `GET /v1/models` on `api.cline.bot` returns `404 Not Found`. Dynamic discovery fails silently or leaves the provider with 0 models.
+2. **Model Identifier Formats**: Models require the specific prefix `cline-pass/` (e.g. `cline-pass/deepseek-v4-flash`, `cline-pass/kimi-k3`).
+3. **Quota Tracking**: Rolling 5-hour and weekly limits need clear in-browser visualization.
+4. **Credential Security**: Storing API keys directly in plain settings is insecure.
+
+**`@goodandready/dsh-clinebot`** provides a complete solution:
+* 🖥️ **Dedicated Settings Page**: Full-width page in DSH Settings (`Settings → ClineBot`).
+* 📊 **Live Quota Dashboard**: Visual progress bars for 5-hour rolling limits and weekly windows from the official `GET /users/me/plan/usage-limits` API.
+* 🔑 **In-UI Key Storage**: Paste your API key directly in the UI; it is saved securely via `ctx.credentials.set()` into `~/.dsh/.credentials.yaml`.
+* 🎯 **Model Picker Management**: Granular checkboxes to choose which models appear in the chat picker.
+* ➕ **Add Custom Models**: Add newly released ClinePass models directly from the UI without waiting for plugin updates.
+* 💬 **Slash-Command `/cline`**: Check quota, limits, latency, and active model directly from the DSH chat console.
+
+---
+
+## 🏛️ Architecture
+
+```mermaid
+graph LR
+    subgraph UI [DSH Web Interface]
+        Page["Dedicated Page (Settings -> ClineBot)"]
+        QuotaBar["5-Hour & Weekly Progress Bars"]
+        KeyInput["Direct Key Paste & Save"]
+        ModelPick["Model Picker Controls & Custom Models"]
+    end
+
+    subgraph PluginHost [dsh-clinebot Host Runtime]
+        HttpEndpoints["API: /api/plugins/dsh-clinebot/*"]
+        ClientCore["lib/cline-client.js"]
+        ModelCatalog["lib/models.js (Curated + Custom)"]
+        SlashCmd["Command: /cline"]
+    end
+
+    subgraph DSHCore [DeepSeek Harness Services]
+        Credentials["Credentials Service (~/.dsh/.credentials.yaml)"]
+        PiAi["Settings: llm-pi-ai.providers.clinebot"]
+    end
+
+    subgraph Upstream [Cline Cloud]
+        ClinePass["api.cline.bot/api/v1/chat/completions"]
+        ClineQuota["api.cline.bot/api/v1/users/me/plan/usage-limits"]
+    end
+
+    Page -->|GET /status & /usage| HttpEndpoints
+    KeyInput -->|POST /save-key| HttpEndpoints
+    ModelPick -->|POST /register & /models| HttpEndpoints
+    HttpEndpoints --> Credentials
+    HttpEndpoints --> ClientCore
+    ClientCore --> ModelCatalog
+    HttpEndpoints -->|Atomic Mutate| PiAi
+    ClientCore -->|Chat| ClinePass
+    ClientCore -->|Usage Limits| ClineQuota
+```
+
+---
+
+## ✨ Features & Module Breakdown
+
+* **`lib/models.js`**:
+  Manages the curated catalog (11 built-in models) and user-added custom models (`getAllModels`, `validateCustomModel`).
+* **`lib/cline-client.js`**:
+  * `fetchUsageLimits`: queries `GET /users/me/plan/usage-limits` and `GET /users/me` with in-memory caching.
+  * `saveCredentialKey`: writes credentials directly into `~/.dsh/.credentials.yaml`.
+  * `smokeChat`: tests latency via non-streaming ping.
+  * `buildPiAiProvider`: builds the DSH `llm-pi-ai` structure (`api: 'openai-completions'`).
+* **`lib/index.js`**:
+  Cordis service module managing routes, credentials, and registering the `/cline` slash command.
+* **`lib/client.js`**:
+  Full-featured dedicated Settings section (`settings.section`, order 28) and plugin accordion (`settings.plugin.item`).
+
+---
+
+## 📦 Installation
+
+```bash
+dsh plugin --profile web add @goodandready/dsh-clinebot
+```
+
+---
+
+## 💬 Slash-Command `/cline`
+
+From any DSH chat session, type `/cline` to inspect quota:
+
+```text
+### 🤖 ClinePass Status (ClinePass ($9.99/mo))
+* Пинг хоста: ✅ 210 мс
+* Активный ключ: CLINEBOT_API_KEY (credentials)
+* Модель по умолчанию: `cline-pass/deepseek-v4-flash`
+
+⏱ 5-часовое окно: [████░░░░░░] 42% (сброс: 18:00)
+📅 Недельное окно: [██████░░░░] 60% (сброс: 08.09)
+* Аккаунт: `developer@example.com`
+```
+
+---
+
+## ⚙️ Configuration Reference (`settings.yaml`)
+
+```yaml
+dsh-clinebot:
+  enabled: true
+  baseUrl: https://api.cline.bot/api/v1
+  apiKeyEnv: CLINEBOT_API_KEY
+  defaultModel: cline-pass/deepseek-v4-flash
+  timeoutMs: 15000
+  smokeTimeoutMs: 25000
+  enabledModels:
+    - cline-pass/deepseek-v4-flash
+    - cline-pass/deepseek-v4-pro
+    - cline-pass/kimi-k3
+    - cline-pass/qwen3.7-max
+  customModels: []
+```
+
+---
+
+## 📄 License
+
+MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)

package/README.ru.md

@@ -0,0 +1,131 @@
+# 📦 @goodandready/dsh-clinebot
+
+<div align="center">
+
+<h3>Нативное подключение провайдера ClineBot / ClinePass для DeepSeek Harness</h3>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@goodandready/dsh-clinebot"><img src="https://img.shields.io/npm/v/@goodandready/dsh-clinebot.svg?style=for-the-badge&color=6366f1&labelColor=1e1b4b" alt="npm version"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/github/license/GooDAnDReaDY/dsh-clinebot.svg?style=for-the-badge&color=10b981&labelColor=064e3b" alt="license"></a>
+  <a href="https://github.com/topics/dsh-plugin"><img src="https://img.shields.io/badge/DSH-Plugin-8b5cf6.svg?style=for-the-badge&labelColor=2e1065" alt="DSH Plugin"></a>
+  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node-20%2B-f59e0b.svg?style=for-the-badge&labelColor=451a03" alt="Node version"></a>
+</p>
+
+<!-- Обязательная кнопка перехода на витрину всех проектов -->
+<p align="center">
+  <a href="https://goodandready.app/"><img src="https://img.shields.io/badge/Все_проекты_автора-goodandready.app-ff4500.svg?style=for-the-badge&logo=rocket&logoColor=white&labelColor=1a1a2e" alt="Все проекты автора"></a>
+</p>
+
+<p align="center">
+  <a href="README.md"><b>🇬🇧 English</b></a> •
+  <a href="README.ru.md"><b>🇷🇺 Русский</b></a> •
+  <a href="README.zh.md"><b>🇨🇳 中文说明</b></a>
+</p>
+
+</div>
+
+---
+
+## ⚡ Обзор и решаемая проблема
+
+**ClinePass** (`https://cline.bot`) — сервис единой фиксированной подписки (\$9.99/мес), предоставляющий разработчикам повышенные лимиты (в 2–5 раз выше стандартных) на передовые open-weights модели программирования и рассуждений через единый OpenAI-совместимый интерфейс (`https://api.cline.bot/api/v1`).
+
+Плагин **`@goodandready/dsh-clinebot`** обеспечивает полноценную интеграцию подписки в DeepSeek Harness:
+* 🖥️ **Отдельная страница в Настройках**: собственная полноэкранная страница в меню Настроек DSH (`Настройки → ClineBot`).
+* 📊 **Дашборд лимитов подписки (Usage)**: наглядные прогресс-бары расхода 5-часового и недельного скользящего окна из официального API `GET /users/me/plan/usage-limits` с таймером сброса.
+* 🔑 **Сохранение ключа прямо из UI**: поле ввода ключа с маскировкой; сохранение напрямую в системный сервис `credentials` (`~/.dsh/.credentials.yaml`) без ручной правки файлов на сервере.
+* 🎯 **Управление моделями в пикере**: включение/выключение отображения конкретных моделей в диалогах чата.
+* ➕ **Добавление кастомных моделей**: форма добавления новых моделей подписки (ID, имя, контекст, Vision) без необходимости ждать обновления плагина.
+* 💬 **Слэш-команда `/cline` в чате**: просмотр остатка квот, задержки и активной модели прямо из чата.
+
+---
+
+## 🏛️ Архитектура
+
+```mermaid
+graph LR
+    subgraph UI [Интерфейс DSH]
+        Page["Отдельная страница (Настройки -> ClineBot)"]
+        QuotaBar["Прогресс-бары 5h и недельного лимита"]
+        KeyInput["Ввод и сохранение API-ключа"]
+        ModelPick["Управление пикером и новые модели"]
+    end
+
+    subgraph PluginHost [Хост-часть dsh-clinebot]
+        HttpEndpoints["API: /api/plugins/dsh-clinebot/*"]
+        ClientCore["lib/cline-client.js"]
+        ModelCatalog["lib/models.js (Встроенные + Кастомные)"]
+        SlashCmd["Слэш-команда: /cline"]
+    end
+
+    subgraph DSHCore [Сервисы DSH]
+        Credentials["Сервис credentials (~/.dsh/.credentials.yaml)"]
+        PiAi["Настройки: llm-pi-ai.providers.clinebot"]
+    end
+
+    subgraph Upstream [Сервер Cline]
+        ClinePass["api.cline.bot/api/v1/chat/completions"]
+        ClineQuota["api.cline.bot/api/v1/users/me/plan/usage-limits"]
+    end
+
+    Page -->|GET /status & /usage| HttpEndpoints
+    KeyInput -->|POST /save-key| HttpEndpoints
+    ModelPick -->|POST /register & /models| HttpEndpoints
+    HttpEndpoints --> Credentials
+    HttpEndpoints --> ClientCore
+    ClientCore --> ModelCatalog
+    HttpEndpoints -->|Атомарная мутация| PiAi
+    ClientCore -->|Чат| ClinePass
+    ClientCore -->|Квоты| ClineQuota
+```
+
+---
+
+## 📦 Быстрая установка
+
+```bash
+dsh plugin --profile web add @goodandready/dsh-clinebot
+```
+
+---
+
+## 💬 Слэш-команда `/cline` в чате
+
+В любой сессии чата введите команду `/cline` для проверки остатка лимитов:
+
+```text
+### 🤖 ClinePass Status (ClinePass ($9.99/mo))
+* Пинг хоста: ✅ 210 мс
+* Активный ключ: CLINEBOT_API_KEY (credentials)
+* Модель по умолчанию: `cline-pass/deepseek-v4-flash`
+
+⏱ 5-часовое окно: [████░░░░░░] 42% (сброс: 18:00)
+📅 Недельное окно: [██████░░░░] 60% (сброс: 08.09)
+* Аккаунт: `developer@example.com`
+```
+
+---
+
+## ⚙️ Таблица конфигурации (`settings.yaml`)
+
+```yaml
+dsh-clinebot:
+  enabled: true
+  baseUrl: https://api.cline.bot/api/v1
+  apiKeyEnv: CLINEBOT_API_KEY
+  defaultModel: cline-pass/deepseek-v4-flash
+  timeoutMs: 15000
+  smokeTimeoutMs: 25000
+  enabledModels:
+    - cline-pass/deepseek-v4-flash
+    - cline-pass/deepseek-v4-pro
+    - cline-pass/kimi-k3
+    - cline-pass/qwen3.7-max
+  customModels: []
+```
+
+---
+
+## 📄 Лицензия
+
+MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)

package/README.zh.md

@@ -0,0 +1,68 @@
+# 📦 @goodandready/dsh-clinebot
+
+<div align="center">
+
+<h3>适用于 DeepSeek Harness 的 ClineBot / ClinePass 原生模型提供商伴侣插件</h3>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@goodandready/dsh-clinebot"><img src="https://img.shields.io/npm/v/@goodandready/dsh-clinebot.svg?style=for-the-badge&color=6366f1&labelColor=1e1b4b" alt="npm version"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/github/license/GooDAnDReaDY/dsh-clinebot.svg?style=for-the-badge&color=10b981&labelColor=064e3b" alt="license"></a>
+  <a href="https://github.com/topics/dsh-plugin"><img src="https://img.shields.io/badge/DSH-Plugin-8b5cf6.svg?style=for-the-badge&labelColor=2e1065" alt="DSH Plugin"></a>
+  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node-20%2B-f59e0b.svg?style=for-the-badge&labelColor=451a03" alt="Node version"></a>
+</p>
+
+<!-- 作者所有项目展示页面链接 -->
+<p align="center">
+  <a href="https://goodandready.app/"><img src="https://img.shields.io/badge/作者所有开源项目-goodandready.app-ff4500.svg?style=for-the-badge&logo=rocket&logoColor=white&labelColor=1a1a2e" alt="所有项目"></a>
+</p>
+
+<p align="center">
+  <a href="README.md"><b>🇬🇧 English</b></a> •
+  <a href="README.ru.md"><b>🇷🇺 Русский</b></a> •
+  <a href="README.zh.md"><b>🇨🇳 中文说明</b></a>
+</p>
+
+</div>
+
+---
+
+## ⚡ 概述与解决的问题
+
+**ClinePass** (`https://cline.bot`) 是一项固定月费（\$9.99/月）的高性价比订阅服务，为开发者提供主流开源代码模型与推理模型 2–5 倍的高并发调用限额，统一通过 OpenAI 兼容接口 (`https://api.cline.bot/api/v1`) 提供服务。
+
+在将 ClinePass 接入 DeepSeek Harness (DSH) 时存在以下挑战：
+1. **缺失 `/v1/models` 接口**：`api.cline.bot` 的 `GET /v1/models` 会直接返回 `404 Not Found`，导致动态模型同步失败。
+2. **专属模型前缀**：所有模型 ID 均需前缀 `cline-pass/`（如 `cline-pass/deepseek-v4-flash`, `cline-pass/kimi-k3`）。
+3. **安全凭据隔离**：禁止在明文配置中直接填写密钥。
+
+**`@goodandready/dsh-clinebot`** 完美解决以上痛点：
+* 🎯 内置包含全部 11 款官方 ClinePass 模型的静态精选目录。
+* 🔐 深度集成 DSH `credentials` 服务 (`~/.dsh/.credentials.yaml`)，凭据隔离无泄漏。
+* 🔄 一键写入 DSH `llm-pi-ai` 模型注册表。
+* 🩺 设置面板内置毫秒级延迟探测与 Smoke Test 测试生成。
+
+---
+
+## 📦 快速安装
+
+在活动的 DeepSeek Harness 配置中安装：
+
+```bash
+dsh plugin --profile web add @goodandready/dsh-clinebot
+```
+
+---
+
+## 🔑 凭据配置
+
+在 DSH 凭据文件 (`~/.dsh/.credentials.yaml`) 中添加 ClinePass 密钥：
+
+```yaml
+CLINEBOT_API_KEY: "your-clinepass-api-key"
+```
+
+---
+
+## 📄 许可证
+
+MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)

package/cordis.patch.yml

@@ -0,0 +1,6 @@
+# @goodandready/dsh-clinebot — ClineBot (ClinePass) companion for DSH.
+# name must be the FULL package specifier (scoped).
+- insert:
+    - id: dsh-clinebot
+      name: '@goodandready/dsh-clinebot'
+      config: {}