@goodandready/dsh-clinebot 0.3.23 → 0.3.25

package/CHANGELOG.md

@@ -5,10 +5,28 @@ All notable changes to `@goodandready/dsh-clinebot` will be documented in this f
 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.3.25] - 2026-09-24
+
+### Fixed
+
+- **SettingsPage "Settings Unavailable" Banner Removal (#96 / GitHub #7)**: Removed the blocking `snapshotStatus === 'unavailable'` render gate in `SettingsPage`. When DSH serves no native settings form or when the page is accessed over non-loopback connections (`persistence === 'memory'`), the page no longer displays the dead-end warning banner and instead smoothly renders its fully functional standalone REST UI from `/dsh-clinebot/status` and `/dsh-clinebot/config`.
+- **Modern DSH `SettingsForms` Adapter**: In `lib/index.js`, implemented a robust adapter for modern DSH `SettingsForms` (`svc.replace` / `svc.update` / `svc.describe`). DSH 0.1.7 removed `sctx.settings.register`, which previously caused `PUT /dsh-clinebot/config` to fail with HTTP 503 `settings not ready` and prevented key changes, account switching, and model toggles from persisting to DSH.
+- **Volatile Field Projection (`volatileConfig`)**: Marked only user-editable settings as `.volatile()`, leaving internal derived fields (`dynamicModels` and deprecated `enabledModels`) non-volatile. Added `volatileConfig` helper to strip non-volatile fields before passing payloads to `SettingsForms.replace`, preventing DSH from rejecting configuration writes with `Config field is not volatile`.
+
+## [0.3.24] - 2026-09-24
+
+### Fixed
+
+- The settings card opens. Host settings are published as a namespace, copied to plain values before use, and account credential names are read as text, so the form renders instead of a React error.
+
 ## [0.3.23] - 2026-09-24
 
 ### Fixed
 - **React Error #185 Infinite Loop Fix (#74 / GitHub #6)**: Restored stable reference constant `SNAPSHOT_READY` in `SettingsPage.getSnapshot` for `useSyncExternalStore`. Returning an inline object literal caused `Object.is` mismatch on every render, triggering an infinite update depth loop (`Maximum update depth exceeded`). The snapshot fallback now returns frozen `SNAPSHOT_READY`, guaranteeing reference stability while keeping the page unblocked in standalone mode.
+- The settings schema marks the user-editable fields volatile, so DSH includes the `dsh-clinebot` namespace and the configuration page is no longer stuck on "host namespace is not ready".
+- Nested fields inside an already volatile array stay plain. The plugin copies host volatile references to plain values before `structuredClone`, so startup does not reject the config or fail to clone a getter.
+- The configuration page renders its own status payload when the host form snapshot is still loading. A missing host namespace still shows the unavailable banner until that payload arrives.
+- Account credential names are read as text. A host volatile reference was sent through as an empty object, and React error #31 replaced the settings card.
 - The settings page binds `configForms.get('dsh-clinebot')` on DSH 0.1.7. The removed `settingsScope` and `lanSettings` services are no longer consulted, so the plugin configuration page can render after install.
 - `GET /dsh-clinebot/status`, `/config`, `/usage`, and `/auth/status` use the same trusted-request check as the write routes. Usage responses keep the quota fields the card shows and omit the raw provider payload.
 - `/cline models` prints the model total in English.
@@ -194,7 +212,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [0.3.4] - 2026-09-08
 
 ### Fixed
-- **Cache Path Resolution**: Corrected POSIX home directory expansion (`~/`) in `resolvePathWithHome` so `~/.dsh/clinebot-models-cache.json` resolves cleanly to `/home/vadim/.dsh/...` instead of root-level paths.
+- **Cache Path Resolution**: Corrected POSIX home directory expansion (`~/`) in `resolvePathWithHome` so `~/.dsh/clinebot-models-cache.json` resolves under the user home directory instead of a root-level path.
 
 ## [0.3.3] - 2026-09-08
 

package/lib/account-pool.js

@@ -3,8 +3,16 @@ import { resolveKeyValue, usageCache, clearUsageCache, clearProbeCache, DEFAULT_
 /**
  * Resolve all accounts in pool with their status and keys.
  */
+function textSetting(value) {
+  let current = value
+  while (current && typeof current === 'object' && !Array.isArray(current) && typeof current.get === 'function') {
+    current = current.get()
+  }
+  return typeof current === 'string' ? current.trim() : ''
+}
+
 export async function resolveAccountPool(ctx, cfg) {
-  const apiKeyEnv = cfg?.apiKeyEnv || DEFAULT_API_KEY_ENV
+  const apiKeyEnv = textSetting(cfg?.apiKeyEnv) || DEFAULT_API_KEY_ENV
   const defaultSlot = {
     id: 'default',
     label: 'Default',
@@ -12,16 +20,16 @@ export async function resolveAccountPool(ctx, cfg) {
   }
   const accounts = Array.isArray(cfg?.accounts) ? cfg.accounts : []
   const allSlots = [defaultSlot, ...accounts]
-  const activeAccount = String(cfg?.activeAccount || '')
+  const activeAccount = textSetting(cfg?.activeAccount)
   const resolved = []
 
   for (let i = 0; i < allSlots.length; i++) {
     const slot = allSlots[i]
-    const envName = slot.apiKeyEnv || (i === 0 ? apiKeyEnv : `CLINEBOT_API_KEY_${i + 1}`)
+    const envName = textSetting(slot.apiKeyEnv) || (i === 0 ? apiKeyEnv : `CLINEBOT_API_KEY_${i + 1}`)
     const keyInfo = await resolveKeyValue(ctx, envName)
     resolved.push({
       id: slot.id || (i === 0 ? 'default' : `account-${i + 1}`),
-      label: slot.label || (i === 0 ? 'Default' : `Account ${i + 1}`),
+      label: textSetting(slot.label) || (i === 0 ? 'Default' : `Account ${i + 1}`),
       apiKeyEnv: envName,
       present: Boolean(keyInfo.value),
       source: keyInfo.source,

package/lib/client.js

@@ -538,12 +538,14 @@ function AccountsSection({ status, busy, handlePinAccount, t }) {
         'tbody',
         null,
         status.accounts.map((acc) => {
-          const isActive = status.activeAccount === acc.apiKeyEnv || (!status.activeAccount && acc.id === 'default')
+          const envName = typeof acc.apiKeyEnv === 'string' ? acc.apiKeyEnv : ''
+          const label = typeof acc.label === 'string' ? acc.label : ''
+          const isActive = status.activeAccount === envName || (!status.activeAccount && acc.id === 'default')
           return React.createElement(
             'tr',
             { key: acc.id },
-            React.createElement('td', null, React.createElement('strong', null, acc.label)),
-            React.createElement('td', null, React.createElement('code', null, acc.apiKeyEnv)),
+            React.createElement('td', null, React.createElement('strong', null, label)),
+            React.createElement('td', null, React.createElement('code', null, envName)),
             React.createElement(
               'td',
               null,
@@ -565,7 +567,7 @@ function AccountsSection({ status, busy, handlePinAccount, t }) {
                       className: 'cb-btn',
                       style: { padding: '4px 8px', fontSize: '11px' },
                       disabled: !!busy,
-                      onClick: () => handlePinAccount(acc.apiKeyEnv),
+                      onClick: () => handlePinAccount(envName),
                     },
                     t('accounts.pin_btn')
                   )
@@ -1196,15 +1198,7 @@ function SettingsPage(props) {
     debounceSaveDisabledModels(nextDisabled)
   }
 
-  if (snapshotStatus === 'unavailable') {
-    return React.createElement(
-      'div',
-      { className: 'cb-page' },
-      React.createElement('div', { className: 'cb-banner-warning' }, t('settings.unavailable'))
-    )
-  }
-
-  if (!status || !draft || snapshotStatus === 'loading') {
+  if (!status || !draft) {
     if (err) {
       return React.createElement(
         'div',

package/lib/config.js

@@ -13,20 +13,30 @@ import {
   getActiveModelIds,
 } from './models.js'
 
+
+// DSH settings.describe only publishes fields marked volatile. Without them the
+// namespace is omitted and the configuration page stays unavailable.
+if (typeof z.prototype?.volatile !== 'function') {
+  z.prototype.volatile = function volatile() {
+    if (this.meta && this.meta.volatile) throw new TypeError('volatile schema is already wrapped')
+    return typeof this.extra === 'function' ? this.extra('volatile', true) : this
+  }
+}
+
 export const NS = 'dsh-clinebot'
 export const LLM_PI_AI_NS = 'llm-pi-ai'
 
 export const Config = z.object({
   enabled: z.boolean().default(true)
-    .description('When true, ClineBot is registered as a model provider in DSH.'),
+    .description('When true, ClineBot is registered as a model provider in DSH.').volatile(),
   baseUrl: z.string().default(DEFAULT_BASE_URL)
-    .description('Base API URL (default: https://api.cline.bot/api/v1).'),
+    .description('Base API URL (default: https://api.cline.bot/api/v1).').volatile(),
   apiKeyEnv: z.string().default(DEFAULT_API_KEY_ENV)
-    .description('Credential / env name containing the ClinePass API key (never store key directly here).'),
+    .description('Credential / env name containing the ClinePass API key (never store key directly here).').volatile(),
   defaultModel: z.string().default(DEFAULT_MODEL_ID)
-    .description('Default model ID for chat and smoke tests.'),
+    .description('Default model ID for chat and smoke tests.').volatile(),
   disabledModels: z.array(z.string()).default([])
-    .description('List of model IDs explicitly disabled by the user (new models are enabled automatically).'),
+    .description('List of model IDs explicitly disabled by the user (new models are enabled automatically).').volatile(),
   enabledModels: z.array(z.string()).default([])
     .description('Deprecated: preserved for backwards compatibility with earlier versions.'),
   dynamicModels: z.array(z.object({
@@ -42,21 +52,52 @@ export const Config = z.object({
   })).default([])
     .description('Models automatically discovered from the official ClinePass subscription plan.'),
   timeoutMs: z.number().default(DEFAULT_TIMEOUT_MS)
-    .description('HTTP probe timeout in milliseconds.'),
+    .description('HTTP probe timeout in milliseconds.').volatile(),
   smokeTimeoutMs: z.number().default(DEFAULT_SMOKE_TIMEOUT_MS)
-    .description('Timeout for smoke chat completions in milliseconds.'),
+    .description('Timeout for smoke chat completions in milliseconds.').volatile(),
   modelsCachePath: z.string().default('~/.dsh/clinebot-models-cache.json')
-    .description('Local on-disk cache path for models snapshot.'),
+    .description('Local on-disk cache path for models snapshot.').volatile(),
   accounts: z.array(z.object({
     label: z.string().default(''),
     apiKeyEnv: z.string(),
   })).default([])
-    .description('Additional accounts for multi-account failover and rate limit rotation.'),
+    .description('Additional accounts for multi-account failover and rate limit rotation.').volatile(),
   activeAccount: z.string().default('')
-    .description('Manually pinned active account envName or empty for auto/default.'),
+    .description('Manually pinned active account envName or empty for auto/default.').volatile(),
 })
 
+
+function isVolatileRef(value) {
+  return !!value && typeof value === 'object' && !Array.isArray(value) && typeof value.get === 'function'
+}
+
+// DSH stores each volatile field as { get }. structuredClone cannot copy that
+// getter, so callers need a plain snapshot before validation.
+export function plainConfig(cfg) {
+  if (isVolatileRef(cfg)) return plainConfig(cfg.get())
+  if (!cfg || typeof cfg !== 'object') return cfg
+  const out = {}
+  for (const key of Object.keys(cfg)) {
+    const value = cfg[key]
+    out[key] = isVolatileRef(value) ? value.get() : value
+  }
+  return out
+}
+
+export function volatileConfig(cfg) {
+  const plain = plainConfig(cfg)
+  if (!plain || typeof plain !== 'object') return plain
+  const out = {}
+  for (const [key, field] of Object.entries(Config.dict || {})) {
+    if (field?.meta?.volatile && Object.hasOwn(plain, key)) {
+      out[key] = plain[key]
+    }
+  }
+  return out
+}
+
 export function publicConfig(cfg) {
+  cfg = plainConfig(cfg)
   const dynamic = Array.isArray(cfg?.dynamicModels) ? cfg.dynamicModels : []
   const allDefaultIds = getDefaultModelIds(dynamic)
 

package/lib/index.js

@@ -1,4 +1,4 @@
-import { Config, publicConfig, NS, LLM_PI_AI_NS } from './config.js'
+import { Config, publicConfig, plainConfig, volatileConfig, NS, LLM_PI_AI_NS } from './config.js'
 import { registerPluginUpdater } from './updater.js'
 import {
   sessionStats,
@@ -29,8 +29,9 @@ export const inject = ['settings', 'webServer', 'credentials']
 export { NS, LLM_PI_AI_NS, Config, sessionStats, recordSessionRequest, resetSessionStats, rotateToNextAccount }
 
 export function apply(ctx, config) {
-  let getConfig = () => config
-  const live = () => (getConfig() ? Config(structuredClone(getConfig())) : config)
+  let currentConfig = config
+  let getConfig = () => currentConfig
+  const live = () => (getConfig() ? Config(structuredClone(plainConfig(getConfig()))) : config)
   let settingsApi
 
   const syncProviderState = async (cfg) => {
@@ -55,14 +56,61 @@ export function apply(ctx, config) {
     autoDiscoverPlanModels(ctx, { live, getSettingsApi: () => settingsApi, syncProviderState })
   }
 
+  const createSettingsAdapter = (svc) => {
+    if (!svc) return undefined
+    if (typeof svc.replace === 'function' || typeof svc.update === 'function' || typeof svc.write === 'function') {
+      const getRevision = () => {
+        try {
+          return svc.describe?.().find((row) => row.ns === NS)?.revision
+        } catch {
+          return undefined
+        }
+      }
+      return {
+        get: () => live(),
+        replace: async (next) => {
+          const parsed = Config(structuredClone(plainConfig(next)))
+          currentConfig = parsed
+          const payload = volatileConfig(parsed)
+          if (typeof svc.replace === 'function') {
+            await svc.replace(NS, payload, getRevision())
+          } else if (typeof svc.update === 'function') {
+            await svc.update(NS, payload, getRevision())
+          }
+          return parsed
+        },
+        update: async (patch) => {
+          const merged = Config({ ...publicConfig(live()), ...plainConfig(patch) })
+          currentConfig = merged
+          const payload = volatileConfig(merged)
+          if (typeof svc.update === 'function') {
+            await svc.update(NS, payload, getRevision())
+          } else if (typeof svc.replace === 'function') {
+            await svc.replace(NS, payload, getRevision())
+          }
+          return merged
+        },
+        watch: (cb) => {
+          if (typeof svc.watch === 'function') return svc.watch(cb)
+          return () => {}
+        },
+      }
+    }
+    return undefined
+  }
+
   if (typeof ctx.inject === 'function') {
     ctx.inject(['settings'], (sctx) => {
-      const scope = sctx.settings.register(NS, Config, { base: config })
-      settingsApi = scope
-      getConfig = () => (scope?.get?.() ?? config) ?? config
-      sctx.effect(() => scope.watch((next) => {
-        syncProviderState(live())
-      }), 'dsh-clinebot: settings')
+      if (typeof sctx.settings?.register === 'function') {
+        const scope = sctx.settings.register(NS, Config, { base: config })
+        settingsApi = scope
+        getConfig = () => (scope?.get?.() ?? config) ?? config
+        sctx.effect(() => scope.watch((next) => {
+          syncProviderState(live())
+        }), 'dsh-clinebot: settings')
+      } else {
+        settingsApi = createSettingsAdapter(sctx.settings)
+      }
       sctx.effect(() => () => {
         getConfig = () => config
         settingsApi = undefined
@@ -79,6 +127,8 @@ export function apply(ctx, config) {
           syncProviderState(live())
         }), 'dsh-clinebot: settings')
       }
+    } else {
+      settingsApi = createSettingsAdapter(settingsService)
     }
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-clinebot",
-  "version": "0.3.23",
+  "version": "0.3.25",
   "description": "DeepSeek Harness companion for ClineBot / ClinePass: dynamic subscription models sync, quota exhaustion warnings, session metrics, dedicated settings page, live usage limits, and /cline slash-command.",
   "license": "MIT",
   "type": "module",