@goodandready/dsh-clinebot 0.3.6 → 0.3.7

package/CHANGELOG.md

@@ -5,6 +5,15 @@ 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.7] - 2026-09-10
+
+### Fixed
+- **Canonical Settings Namespace Registration** (Issue #16): Moved settings declaration in `lib/index.js` to `ctx.inject(['settings'], (sctx) => { sctx.settings.register(NS, Config, { base: config }) })`, guaranteeing synchronous/asynchronous namespace availability and reactive config watching via `live()`.
+- **Top-Level Section Removal**: Removed the unauthorized fallback to `settings.section` in `lib/client.js`, strictly confining the plugin UI to the standard `settings.plugin.item` slot under Settings → Plugins → Plugin Settings.
+- **Safe Service Resolution**: Replaced direct property access `ctx.credentials` with safe proxy lookup `(ctx?.get && ctx.get('credentials')) || ctx?.credentials`.
+- **Client Mirror Invalidation & Scope Sync**: Added `refreshMirrorUntilVisible(ctx)` in `lib/client.js` to trigger settings mirror re-reads until the namespace is visible in the web client, and synchronized multi-account changes directly through `scope.set('activeAccount', accountEnv)`.
+- **Duplicate-Safe Locales**: Wrapped client dictionary registration with duplicate-safe guards (`ctx.locale.register()`) preventing registration collision errors.
+
 ## [0.3.6] - 2026-09-09
 
 ### Fixed

package/docs/design/DESIGN.md

@@ -7,17 +7,19 @@
 The plugin consists of two runtime boundaries conforming to DSH authoring standards:
 
 ### 2.1 Host Runtime (`lib/index.js`, `lib/cline-client.js`, `lib/models.js`, `lib/http.js`)
-* **Cordis Service Registration**: Injects `['settings', 'webServer', 'credentials']`.
-* **Credential Isolation**: The plugin NEVER stores plain API keys in its configuration. The setting `apiKeyEnv` holds the credential identifier (default: `CLINEBOT_API_KEY`), resolved via `ctx.credentials.resolve()` or `process.env`.
+* **Cordis Service Registration**: Declares `inject = ['settings', 'webServer', 'credentials']` and registers the settings namespace dynamically via `ctx.inject(['settings'], (sctx) => { sctx.settings.register(NS, Config, { base: config }) })`. This guarantees that the configuration schema, default values, and reactive watchers are declared and available to the host and client settingsScope without timing issues.
+* **Safe Service Resolution**: Service lookups utilize defensive proxy resolution `(ctx?.get && ctx.get('credentials')) || ctx?.credentials` to prevent `undefined` properties on Cordis proxies.
+* **Credential Isolation**: The plugin NEVER stores plain API keys in its configuration. The setting `apiKeyEnv` holds the credential identifier (default: `CLINEBOT_API_KEY`), resolved via `ctx.get('credentials').resolve()` or `process.env`.
 * **State Synchronization & Auto-Registration**: Mutates the core `llm-pi-ai` settings space (`op: 'set', path: ['providers', 'clinebot']`) declaratively and automatically when enabled or key is saved.
 * **Auto-Discovery & `disabledModels`**: Features automatic background polling of subscription plan models (`GET /api/v1/users/me/plan`). User preferences are tracked via `disabledModels: []`, ensuring newly added plan models appear enabled by default in the DSH chat picker without manual re-synchronization.
 
 ### 2.2 Client Runtime (`lib/client.js`)
 * Self-registering module via `window.__ModuleLoader__.load({ id: '@goodandready/dsh-clinebot', factory })`.
 * Injects `['slots', 'locale', 'settingsScope']`.
-* Slots into `settings.plugin.item` (primary) with `key: NS` and `locale: NS`, and graceful fallback to `settings.section` if not declared.
-* Registers localized `en` and `ru` dictionaries via `ctx.locale.register()`.
-* Reactive binding via `ctx.settingsScope.bind({ namespace: NS })` with `useSyncExternalStore` guarding against `unavailable` / `loading` snapshot states.
+* Slots strictly and exclusively into `settings.plugin.item` (`key: NS`, `locale: NS`). Standalone top-level `settings.section` registration is omitted to maintain clean primary navigation in DSH and prevent side-list pollution.
+* Uses `refreshMirrorUntilVisible(ctx)` to invalidate and re-read the client settings mirror until the namespace is reported ready by the host.
+* Registers localized `en` and `ru` dictionaries with duplicate-safe guards (`ctx.locale.register()`).
+* Reactive binding via `((ctx?.get && ctx.get('lanSettings')) || ctx?.settingsScope).bind({ namespace: NS })` with `useSyncExternalStore` guarding against `unavailable` / `loading` snapshot states. Form mutations write directly to `scope.set()`.
 * Uses native design tokens (`--dsw-alias-...`) with full dark/light theme support.
 * Injects isolated style tag tagged with `data-dsh-plugin="dsh-clinebot"`.
 

package/lib/client.js

@@ -1,5 +1,4 @@
-// Dedicated Settings Page: Settings → ClineBot (settings.section)
-// & Plugin Card (settings.plugin.item).
+// Plugin Settings Card (settings.plugin.item).
 window.__ModuleLoader__.load({
   id: '@goodandready/dsh-clinebot',
   factory: (require) => {
@@ -357,9 +356,10 @@ window.__ModuleLoader__.load({
       const t = props?.t || makeT(ru, en)
 
       const scope = React.useMemo(() => {
-        if (!ctx?.settingsScope?.bind) return undefined
+        const s = (ctx?.get && ctx.get('lanSettings')) || ctx?.settingsScope
+        if (!s?.bind) return undefined
         try {
-          return ctx.settingsScope.bind({ namespace: NS })
+          return s.bind({ namespace: NS })
         } catch (_) {
           return undefined
         }
@@ -377,11 +377,11 @@ window.__ModuleLoader__.load({
       }, [scope])
 
       const getSnapshot = React.useCallback(() => {
-        if (!scope?.getSnapshot) return SNAPSHOT_READY
+        if (!scope?.getSnapshot) return SNAPSHOT_LOADING
         try {
-          return scope.getSnapshot() || SNAPSHOT_READY
+          return scope.getSnapshot() || SNAPSHOT_LOADING
         } catch (_) {
-          return SNAPSHOT_READY
+          return SNAPSHOT_LOADING
         }
       }, [scope])
 
@@ -390,7 +390,7 @@ window.__ModuleLoader__.load({
         getSnapshot,
         React.useCallback(() => SNAPSHOT_LOADING, [])
       )
-      const snapshotStatus = snapshot?.status || 'ready'
+      const snapshotStatus = snapshot?.status || 'loading'
 
       const [status, setStatus] = React.useState(null)
       const [draft, setDraft] = React.useState(null)
@@ -420,6 +420,12 @@ window.__ModuleLoader__.load({
         load().catch((e) => setErr(String(e.message || e)))
       }, [load])
 
+      React.useEffect(() => {
+        if (snapshotStatus === 'ready' && snapshot?.value && typeof snapshot.value === 'object') {
+          setDraft((prev) => (prev ? { ...prev, ...snapshot.value } : snapshot.value))
+        }
+      }, [snapshotStatus, snapshot?.value])
+
       // Save Key handler
       async function handleSaveKey() {
         if (!apiKeyInput.trim()) {
@@ -570,6 +576,9 @@ window.__ModuleLoader__.load({
 
       // Pin active account
       async function handlePinAccount(accountEnv) {
+        if (scope && snapshotStatus === "ready") {
+          try { await scope.set("activeAccount", accountEnv) } catch (_) {}
+        }
         setBusy(`pin-${accountEnv}`)
         setErr('')
         try {
@@ -1212,49 +1221,92 @@ window.__ModuleLoader__.load({
       )
     }
 
+    function refreshMirrorUntilVisible(ctx) {
+      const visible = () => {
+        try {
+          const s = (ctx?.get && ctx.get('lanSettings')) || ctx?.settingsScope
+          const view = s?.describe?.()?.getSnapshot?.()?.view
+          return !!view && Array.isArray(view.namespaces) && view.namespaces.some((row) => row.ns === NS)
+        } catch (_) {
+          return false
+        }
+      }
+      if (visible()) return () => {}
+      let tries = 0
+      const timer = setInterval(() => {
+        if (visible() || tries >= 15) { clearInterval(timer); return }
+        tries += 1
+        try {
+          const s = (ctx?.get && ctx.get('lanSettings')) || ctx?.settingsScope
+          s?.describe?.()?.load?.()
+        } catch (_) {}
+      }, 1000)
+      return () => clearInterval(timer)
+    }
+
     function apply(ctx) {
+      const addLocale = (locale, dictionary) => {
+        try {
+          return ctx.locale.register(NS, locale, dictionary)
+        } catch (_) {
+          return () => {}
+        }
+      }
       if (ctx.locale && ctx.locale.register) {
-        try { ctx.locale.register(NS, { en, ru }) } catch (_) {}
+        if (typeof ctx.effect === 'function') {
+          ctx.effect(() => {
+            const undo = [addLocale('en', en), addLocale('ru', ru)]
+            return () => { for (const off of undo) off() }
+          }, 'dsh-clinebot: dictionaries')
+        } else {
+          addLocale('en', en)
+          addLocale('ru', ru)
+        }
       }
-      const t = (ctx.locale && ctx.locale.bind) ? ctx.locale.bind(NS) : makeT(ru, en)
 
-      let placed = false
-      try {
-        const res = ctx.slots.inject('settings.plugin.item', () => {
-          placed = true
-          return ctx.slots.register(
-            {
-              name: 'settings.plugin.item',
-              key: NS,
-              locale: NS,
-              inject: () => ({ ctx }),
-            },
-            (props) => React.createElement(ErrorBoundary, null, React.createElement(PluginCard, { ...props, ctx: (props && props.ctx) || ctx }))
-          )
-        })
-        if (res === null) placed = false
-      } catch (_) {
-        placed = false
+      if (typeof ctx.effect === 'function') {
+        ctx.effect(
+          () => refreshMirrorUntilVisible(ctx),
+          'dsh-clinebot: re-read the settings mirror until our namespace appears',
+        )
       }
 
-      // Fallback to settings.section if settings.plugin.item is not declared
-      if (!placed) {
-        try {
-          ctx.slots.inject('settings.section', () => {
-            return ctx.slots.register(
-              {
-                name: 'settings.section',
-                id: '@goodandready/dsh-clinebot',
-                order: 28,
-                locale: NS,
-                label: () => t('title'),
-                inject: () => ({ ctx }),
-              },
-              (props) => React.createElement(ErrorBoundary, null, React.createElement(SettingsPage, { ...props, ctx: (props && props.ctx) || ctx }))
-            )
-          })
-        } catch (_) {}
+      function registerSlotWhenReady(slotName, registerFn) {
+        if (!ctx.slots) return
+        if (typeof ctx.slots.inject === 'function') {
+          try {
+            ctx.slots.inject(slotName, () => {
+              try {
+                return registerFn()
+              } catch (err) {
+                console.warn('[dsh-clinebot] Error registering slot ' + slotName + ':', err)
+              }
+            })
+            return
+          } catch (err) {
+            console.warn('[dsh-clinebot] Failed to inject slot ' + slotName + ':', err)
+          }
+        }
+        if (typeof ctx.slots.register === 'function') {
+          try {
+            registerFn()
+          } catch (err) {
+            console.warn('[dsh-clinebot] Failed direct registration for ' + slotName + ':', err)
+          }
+        }
       }
+
+      registerSlotWhenReady('settings.plugin.item', () =>
+        ctx.slots.register(
+          {
+            name: 'settings.plugin.item',
+            key: NS,
+            locale: NS,
+            inject: () => ({ ctx }),
+          },
+          (props) => React.createElement(ErrorBoundary, null, React.createElement(PluginCard, { ...props, ctx: (props && props.ctx) || ctx }))
+        )
+      )
     }
 
     module.exports = { apply, inject: ['slots', 'locale', 'settingsScope'] }

package/lib/index.js

@@ -122,9 +122,10 @@ function resolvePathWithHome(p) {
 
 async function resolveKeyValue(ctx, apiKeyEnv) {
   const refName = String(apiKeyEnv || DEFAULT_API_KEY_ENV).trim() || DEFAULT_API_KEY_ENV
-  if (ctx?.credentials && typeof ctx.credentials.resolve === 'function') {
+  const creds = (ctx?.get && ctx.get('credentials')) || ctx?.credentials
+  if (creds && typeof creds.resolve === 'function') {
     try {
-      const hit = await ctx.credentials.resolve(credentialRef(refName))
+      const hit = await creds.resolve(credentialRef(refName))
       if (hit?.value) {
         return { envName: refName, value: hit.value, source: 'credentials' }
       }
@@ -323,7 +324,8 @@ function formatProgressBar(pct, totalWidth = 10) {
 }
 
 export function apply(ctx, config) {
-  let liveCfg = Config(structuredClone(config || {}))
+  let getConfig = () => config
+  const live = () => (getConfig() ? Config(structuredClone(getConfig())) : config)
   let settingsApi
 
   // Declarative sync helper: auto-registers or unregisters provider based on config & key availability
@@ -355,7 +357,7 @@ export function apply(ctx, config) {
       if ((!pub.dynamicModels || !pub.dynamicModels.length) && cacheFile) {
         const fromDisk = await loadModelsDiskCache(cacheFile)
         if (Array.isArray(fromDisk) && fromDisk.length && settingsApi?.replace) {
-          const next = Config({ ...liveCfg, dynamicModels: fromDisk })
+          const next = Config({ ...live(), dynamicModels: fromDisk })
           await settingsApi.replace(next)
           await syncProviderState(next)
         }
@@ -376,7 +378,7 @@ export function apply(ctx, config) {
 
         if (hasNew && settingsApi?.replace) {
           const next = Config({
-            ...liveCfg,
+            ...live(),
             dynamicModels: usageData.dynamicModels,
           })
           await settingsApi.replace(next)
@@ -391,23 +393,37 @@ export function apply(ctx, config) {
     }
   }
 
-  const settingsService = ctx.get('settings')
-  if (typeof settingsService?.register === 'function') {
-    const scope = settingsService.register(NS, Config, { base: config })
-    settingsApi = scope
-    liveCfg = Config(scope.get() ?? config)
-    ctx.effect(() => scope.watch((next) => {
-      liveCfg = Config(next ?? config)
-      syncProviderState(liveCfg)
-    }), 'dsh-clinebot: settings')
+  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')
+      sctx.effect(() => () => {
+        getConfig = () => config
+        settingsApi = undefined
+      })
+    })
+  } else {
+    const settingsService = (ctx?.get && ctx.get('settings')) || ctx?.settings
+    if (typeof settingsService?.register === 'function') {
+      const scope = settingsService.register(NS, Config, { base: config })
+      settingsApi = scope
+      getConfig = () => (scope?.get?.() ?? config) ?? config
+      if (typeof ctx.effect === 'function') {
+        ctx.effect(() => scope.watch((next) => {
+          syncProviderState(live())
+        }), 'dsh-clinebot: settings')
+      }
+    }
   }
 
-  const live = () => liveCfg
-
   // On startup: ensure provider is synced to llm-pi-ai if key is present
-  syncProviderState(liveCfg)
+  syncProviderState(live())
   // Background discover plan models on startup
-  setTimeout(() => autoDiscoverPlanModels(liveCfg), 500)
+  setTimeout(() => autoDiscoverPlanModels(live()), 500)
 
   // Web server HTTP route handlers
   if (ctx.webServer?.register) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-clinebot",
-  "version": "0.3.6",
+  "version": "0.3.7",
   "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",