@fonlan/dsh-quick-commands 0.1.5 → 0.1.7

package/src/client/settings-section.tsx

@@ -0,0 +1,192 @@
+/**
+ * Quick-commands settings page (设置 → 侧栏「快捷命令」).
+ *
+ * Registers into the "settings.section" list slot, so the page owns one entry
+ * in the settings sidebar and renders in the settings panel's content column.
+ * The header is static (title + one-line summary) over the always-visible
+ * body: the workspace / command-set editor and the popup anchor preference.
+ * Body edits instant-save per change; partial rows (empty name/command)
+ * persist while the user types.
+ */
+import { useEffect, useRef, useState } from 'react'
+import { PlusIcon, TrashIcon } from './icons'
+import { quickApi } from './api'
+import { anchorOf, type QuickRosterEntry, type QuickCommandsSettings } from '../shared/contract'
+import './settings-section.css'
+
+interface Props {
+  t: (key: string) => string
+}
+
+interface RosterState {
+  loaded: boolean
+  entries: QuickRosterEntry[]
+  anchor: QuickCommandsSettings['popupAnchor']
+}
+
+type CommandDraft = { name: string; command: string }
+
+export function QuickCommandsSettingsSection({ t }: Props): JSX.Element {
+  const [state, setState] = useState<RosterState>({ loaded: false, entries: [], anchor: 'corner' })
+  const [error, setError] = useState<string | null>(null)
+  // Guard concurrent saves: the last write wins via a monotonically bumped token.
+  const saveToken = useRef(0)
+
+  const load = async (): Promise<void> => {
+    try {
+      const [entries, settings] = await Promise.all([quickApi.workspacesList(), quickApi.settingsGet()])
+      setState({ loaded: true, entries, anchor: anchorOf(settings.popupAnchor) })
+      setError(null)
+    } catch (e) {
+      setState((s) => ({ ...s, loaded: true }))
+      setError(e instanceof Error ? e.message : String(e))
+    }
+  }
+
+  useEffect(() => {
+    void load()
+  }, [])
+
+  /** Instant-save the workspace's whole command set; optimistic UI. */
+  const saveCommands = async (workspaceId: string, commands: CommandDraft[]): Promise<void> => {
+    const token = ++saveToken.current
+    try {
+      const next = await quickApi.settingsSetCommands(workspaceId, commands)
+      if (token !== saveToken.current) return
+      setState((s) => ({
+        ...s,
+        anchor: next.popupAnchor,
+        entries: s.entries.map((e) => (e.workspaceId === workspaceId ? { ...e, commands } : e)),
+      }))
+      setError(null)
+    } catch (e) {
+      setError(e instanceof Error ? e.message : String(e))
+      // Re-sync to server truth on failure.
+      void load()
+    }
+  }
+
+  /** Compute the next command list for a workspace, THEN save + update state. */
+  const mutateCommands = (workspaceId: string, next: (current: CommandDraft[]) => CommandDraft[]): void => {
+    const entry = state.entries.find((e) => e.workspaceId === workspaceId)
+    if (entry === undefined) return
+    const commands = next(entry.commands)
+    // Optimistic update first (row stays visible immediately), then persist.
+    setState((s) => ({
+      ...s,
+      entries: s.entries.map((e) => (e.workspaceId === workspaceId ? { ...e, commands } : e)),
+    }))
+    void saveCommands(workspaceId, commands)
+  }
+
+  const patchEntry = (workspaceId: string, index: number, field: 'name' | 'command', value: string): void => {
+    mutateCommands(workspaceId, (current) =>
+      current.map((c, i) => (i === index ? { ...c, [field]: value } : c)),
+    )
+  }
+
+  const addCommand = (workspaceId: string): void => {
+    mutateCommands(workspaceId, (current) => [...current, { name: '', command: '' }])
+  }
+
+  const removeCommand = (workspaceId: string, index: number): void => {
+    mutateCommands(workspaceId, (current) => current.filter((_, i) => i !== index))
+  }
+
+  const setAnchor = async (anchor: QuickCommandsSettings['popupAnchor']): Promise<void> => {
+    setState((s) => ({ ...s, anchor }))
+    try {
+      const next = await quickApi.settingsSetAnchor(anchor)
+      setState((s) => ({ ...s, anchor: anchorOf(next.popupAnchor) }))
+    } catch (e) {
+      setError(e instanceof Error ? e.message : String(e))
+      void load()
+    }
+  }
+
+  const title = t('cardTitle')
+  const description = t('sectionSub')
+
+  return (
+    <div className="qc-page">
+      <header className="qc-page-head">
+        <h3 className="qc-page-title">{title}</h3>
+        <p className="qc-page-sub">{description}</p>
+      </header>
+      <div className="qc-settings-body">
+        <p className="qc-settings-intro">{t('cardIntro')}</p>
+
+        <div className="qc-settings-anchor">
+          <span className="qc-settings-anchor-label">{t('cardAnchor')}</span>
+          <label className="qc-settings-radio">
+            <input
+              type="radio"
+              name="qc-anchor"
+              checked={state.anchor === 'corner'}
+              onChange={() => void setAnchor('corner')}
+            />
+            {t('cardAnchorCorner')}
+          </label>
+          <label className="qc-settings-radio">
+            <input
+              type="radio"
+              name="qc-anchor"
+              checked={state.anchor === 'button'}
+              onChange={() => void setAnchor('button')}
+            />
+            {t('cardAnchorButton')}
+          </label>
+        </div>
+
+        {error !== null && <div className="qc-settings-error">{t('cardSaveError')}: {error}</div>}
+
+        {state.loaded && state.entries.length === 0 && (
+          <p className="qc-settings-empty">{t('cardNoWorkspaces')}</p>
+        )}
+
+        {state.entries.map((entry) => (
+          <section key={entry.workspaceId} className="qc-settings-workspace">
+            <header className="qc-settings-workspace-head">
+              <span className="qc-settings-workspace-title">{entry.title || entry.path || entry.workspaceId}</span>
+              <span className="qc-settings-workspace-path">{entry.path}</span>
+            </header>
+            {entry.commands.length === 0 && (
+              <p className="qc-settings-no-commands">{t('cardNoCommands')}</p>
+            )}
+            {entry.commands.map((command, index) => (
+              <div key={`${entry.workspaceId}-${index}`} className="qc-settings-command">
+                <input
+                  className="qc-settings-field qc-settings-field-name"
+                  placeholder={t('cardName')}
+                  value={command.name}
+                  aria-label={t('cardName')}
+                  onChange={(e) => patchEntry(entry.workspaceId, index, 'name', e.target.value)}
+                />
+                <input
+                  className="qc-settings-field qc-settings-field-command"
+                  placeholder={t('cardCommand')}
+                  value={command.command}
+                  aria-label={t('cardCommand')}
+                  onChange={(e) => patchEntry(entry.workspaceId, index, 'command', e.target.value)}
+                />
+                <button
+                  type="button"
+                  className="qc-settings-icon-btn"
+                  aria-label={t('cardRemove')}
+                  title={t('cardRemove')}
+                  onClick={() => removeCommand(entry.workspaceId, index)}
+                >
+                  <TrashIcon size={14} />
+                </button>
+              </div>
+            ))}
+            <button type="button" className="qc-settings-add-btn" onClick={() => addCommand(entry.workspaceId)}>
+              <PlusIcon size={14} />
+              {t('cardAddCommand')}
+            </button>
+          </section>
+        ))}
+      </div>
+    </div>
+  )
+}

package/src/index.ts

@@ -15,16 +15,23 @@
 import type { Context } from '@deepseek-ai/cordis'
 import { QuickCommandRunner, type RemoteBackend } from './server/runner.js'
 import { readHostConfig } from './server/remote.js'
-import { registerSettings } from './server/settings.js'
+import { QuickCommandsSettingsSchema, registerSettings } from './server/settings.js'
 import { registerApiRoutes } from './server/rpc.js'
+import type { QuickCommandsSettings } from './shared/contract.js'
 
 export const name = '@fonlan/dsh-quick-commands'
 
 export const inject = ['settings']
 
-/** No plugin-level config; all configuration lives in the settings namespace. */
-export function apply(ctx: Context): void {
-  const settings = registerSettings(ctx)
+// The entry config IS this plugin's settings document (workspace command sets
+// + popup preferences). Its fields are declared volatile, so the settings
+// plane edits them without remounting the entry and `apply` receives live
+// handles rather than snapshots — see server/settings.ts for the reads.
+export const Config = QuickCommandsSettingsSchema
+
+/** Configuration rides the entry config; edits persist through the settings service. */
+export function apply(ctx: Context, config: QuickCommandsSettings): void {
+  const settings = registerSettings(ctx, config)
   const subprocess = ctx.get('subprocess')
   if (subprocess === undefined) {
     ctx.logger?.warn?.('@fonlan/dsh-quick-commands: subprocess service unavailable; commands cannot run')

package/src/server/settings.ts

@@ -1,13 +1,22 @@
 /**
  * User-facing plugin settings (per-workspace command sets + popup anchor),
- * persisted through the settings service namespace `quick-commands`.
- * The DSH settings service requires a lowercase kebab-case namespace
- * (/^[a-z][a-z0-9-]*$/), so the scoped package name cannot be used here.
+ * carried by this bundle's entry config: dsh >= 0.1.7 owns plugin settings as
+ * entry config (the plugin's `Config` schema) and persists edits through
+ * `settings.update`.
+ *
+ * All three fields are declared `volatile()` — that is what makes them
+ * writable by the settings plane — and schemastery hands a volatile field to
+ * `apply()` as a LIVE HANDLE (`{ get() }`), not as the value. Reading the raw
+ * field therefore yields the handle object, which silently destroys the whole
+ * document: `Array.isArray(handle)` is false, JSON renders `{}`, and a
+ * `.default('corner')` union arrives as the handle rather than a literal.
+ * Every read goes through {@link readField} instead, which unwraps handles and
+ * still accepts plain values (hosts that resolve the config without the
+ * volatile wrapper).
  */
 import type { Context } from '@deepseek-ai/cordis'
 import z from '@deepseek-ai/schemastery'
 import type { QuickCommandsSettings, QuickCommandEntry, QuickPopupSize, WorkspaceCommands } from '../shared/contract.js'
-import type {} from '@deepseek-ai/dsh-settings'
 
 export const QUICK_COMMANDS_NS = 'quick-commands'
 
@@ -28,27 +37,41 @@ const WorkspaceCommandsSchema = z.object({
 })
 
 export const QuickCommandsSettingsSchema: z<QuickCommandsSettings> = z.object({
-  workspaces: z.array(WorkspaceCommandsSchema).max(500),
-  popupAnchor: z.union([z.const('corner'), z.const('button')]).default('corner'),
+  // Values are addressed by index (array edits), so the whole array is the
+  // volatile handle the settings plane swaps in place.
+  workspaces: z.array(WorkspaceCommandsSchema).max(500).volatile(),
+  popupAnchor: z.union([z.const('corner'), z.const('button')]).default('corner').volatile(),
   // No default on purpose: a missing popupSize stays ABSENT in the resolved
   // document, so the client can distinguish "never resized" (per-anchor
-  // default size) from a user-chosen size.
+  // default size) from a user-chosen size. Semantics match the runtime value:
+  // never resized resolves to `{}` (schemastery's implicit object default).
   popupSize: z.object({
     width: z.number().min(320).max(8192),
     height: z.number().min(200).max(8192),
-  }),
+  }).volatile(),
 })
 
-const DEFAULT_SETTINGS: QuickCommandsSettings = {
-  workspaces: [],
-  popupAnchor: 'corner',
+/** Live handle schemastery wraps around one `volatile()` config field. */
+interface VolatileField<T> {
+  get(): T
 }
 
-/** Structural settings-service subset; the real service resolves the schema. */
-interface SettingsServiceLike {
-  register(ns: unknown, schema: unknown): unknown
-  update(ns: unknown, patch: Record<string, unknown>, expectedRevision?: number): Promise<unknown>
-  mutate?(ns: unknown, ops: readonly unknown[], expectedRevision?: number): Promise<unknown>
+/**
+ * Read one config field. A volatile field arrives as a handle (dsh >= 0.1.7)
+ * and is read through `.get()` on EVERY access, so edits made through the
+ * settings plane are visible immediately; hosts that hand the plain value keep
+ * working unchanged.
+ */
+function readField<T>(field: unknown, fallback: T): T {
+  if (field === undefined || field === null) return fallback
+  const handle = field as Partial<VolatileField<T>>
+  const value = typeof handle.get === 'function' ? handle.get() : (field as T)
+  return value === undefined || value === null ? fallback : value
+}
+
+/** Structural settings-service subset used for persistence. */
+interface SettingsUpdateFace {
+  update(ns: string, patch: Record<string, unknown>, expectedRevision?: number): Promise<unknown>
 }
 
 /** Settings service face for the quick-commands engine. */
@@ -64,35 +87,57 @@ export interface QuickCommandsSettingsFace {
   setPopupSize(size: QuickPopupSize): Promise<void>
 }
 
-export function registerSettings(ctx: Context): QuickCommandsSettingsFace {
-  let current: QuickCommandsSettings = { ...DEFAULT_SETTINGS, workspaces: [] }
-  let service: SettingsServiceLike | undefined
+export function registerSettings(ctx: Context, config: QuickCommandsSettings): QuickCommandsSettingsFace {
+  const readWorkspaces = (): WorkspaceCommands[] => {
+    const value = readField<unknown>(config?.workspaces, [])
+    return Array.isArray(value) ? value as WorkspaceCommands[] : []
+  }
+  const readAnchor = (): QuickCommandsSettings['popupAnchor'] =>
+    (readField<unknown>(config?.popupAnchor, 'corner') === 'button' ? 'button' : 'corner')
+  const readPopupSize = (): QuickPopupSize | undefined => {
+    const value = readField<unknown>(config?.popupSize, undefined)
+    if (typeof value !== 'object' || value === null) return undefined
+    const { width, height } = value as { width?: unknown; height?: unknown }
+    // `{}` (never resized) and any partially written size read as absent.
+    if (typeof width !== 'number' || typeof height !== 'number') return undefined
+    if (!Number.isFinite(width) || !Number.isFinite(height)) return undefined
+    return { width: Math.round(width), height: Math.round(height) }
+  }
+  /** Current document, rebuilt from the live config fields on every read. */
+  const readDocument = (): QuickCommandsSettings => {
+    const size = readPopupSize()
+    return {
+      workspaces: readWorkspaces(),
+      popupAnchor: readAnchor(),
+      ...(size === undefined ? {} : { popupSize: size }),
+    }
+  }
+  let service: SettingsUpdateFace | undefined
 
+  // Optional settings service: without one the commands still run from the
+  // entry config; they just cannot persist edits.
   ctx.inject(['settings'], (sctx) => {
-    service = sctx.settings as unknown as SettingsServiceLike
-    const scope = service.register(QUICK_COMMANDS_NS, QuickCommandsSettingsSchema) as {
-      get(): QuickCommandsSettings
-      watch(callback: (next: QuickCommandsSettings) => void): () => void
-    }
-    current = scope.get()
-    scope.watch((next) => { current = next })
+    service = (sctx as unknown as { settings?: SettingsUpdateFace }).settings
   })
 
   async function persist(patch: Record<string, unknown>): Promise<void> {
     if (service === undefined) {
       throw new Error('@fonlan/dsh-quick-commands: settings service is not available in this profile')
     }
+    // The write lands in this entry's config: the settings plane either swaps
+    // the volatile handles in place or re-applies the entry — both paths are
+    // picked up by the next read, which is why no local mirror is kept here.
     await service.update(QUICK_COMMANDS_NS, patch)
   }
 
   return {
-    get: () => current,
+    get: readDocument,
     commandsOf: (workspaceId) => {
-      const set = current.workspaces.find((w) => w.workspaceId === workspaceId)
+      const set = readWorkspaces().find((w) => w.workspaceId === workspaceId)
       return set === undefined ? [] : set.commands
     },
     setCommands: async (workspaceId, commands) => {
-      const next: WorkspaceCommands[] = current.workspaces.filter((w) => w.workspaceId !== workspaceId)
+      const next = readWorkspaces().filter((w) => w.workspaceId !== workspaceId)
       if (commands.length > 0) next.push({ workspaceId, commands })
       await persist({ workspaces: next })
     },

package/src/shared/contract.ts

@@ -38,6 +38,16 @@ export interface QuickCommandsSettings {
   popupSize?: QuickPopupSize
 }
 
+/**
+ * The document's anchor as a usable literal. Wire data is defensive by
+ * contract: an older host can still answer with schemastery's empty-object
+ * resolution (`{}`) for this field, which must never reach a CSS class name or
+ * a radio `checked` comparison.
+ */
+export function anchorOf(value: unknown): 'corner' | 'button' {
+  return value === 'button' ? 'button' : 'corner'
+}
+
 /** Placeholder substitution values resolved for one execution. */
 export interface QuickRunPlaceholders {
   /** Workspace root path (also the execution cwd). */

package/src/client/settings-card.tsx

@@ -1,209 +0,0 @@
-/**
- * Quick-commands settings card (设置 → 插件配置): an expandable plugin card —
- * header (title + description + chevron) collapsed by default, body reveals
- * the workspace × command-set editor and the popup anchor preference. Body
- * edits instant-save per change; partial rows (empty name/command) persist
- * while the user types.
- *
- * Mirrors the official PluginCard disclosure pattern (header button with
- * aria-expanded, rotate-180 chevron, body separated by a top border).
- */
-import { useEffect, useRef, useState } from 'react'
-import {
-  IconChevronDownOutline14,
-  IconPlusOutline16,
-  IconTrashOutline16,
-} from '@deepseek-ai/dsh-client-ui-primitives'
-import { quickApi } from './api'
-import type { QuickRosterEntry, QuickCommandsSettings } from '../shared/contract'
-
-interface Props {
-  t: (key: string) => string
-}
-
-interface RosterState {
-  loaded: boolean
-  entries: QuickRosterEntry[]
-  anchor: QuickCommandsSettings['popupAnchor']
-}
-
-type CommandDraft = { name: string; command: string }
-
-export function QuickCommandsSettingsCard({ t }: Props): JSX.Element {
-  // Card-local disclosure state (a reading gesture, like the official card).
-  const [open, setOpen] = useState(false)
-  const [state, setState] = useState<RosterState>({ loaded: false, entries: [], anchor: 'corner' })
-  const [error, setError] = useState<string | null>(null)
-  // Guard concurrent saves: the last write wins via a monotonically bumped token.
-  const saveToken = useRef(0)
-
-  const load = async (): Promise<void> => {
-    try {
-      const [entries, settings] = await Promise.all([quickApi.workspacesList(), quickApi.settingsGet()])
-      setState({ loaded: true, entries, anchor: settings.popupAnchor })
-      setError(null)
-    } catch (e) {
-      setState((s) => ({ ...s, loaded: true }))
-      setError(e instanceof Error ? e.message : String(e))
-    }
-  }
-
-  useEffect(() => {
-    void load()
-  }, [])
-
-  /** Instant-save the workspace's whole command set; optimistic UI. */
-  const saveCommands = async (workspaceId: string, commands: CommandDraft[]): Promise<void> => {
-    const token = ++saveToken.current
-    try {
-      const next = await quickApi.settingsSetCommands(workspaceId, commands)
-      if (token !== saveToken.current) return
-      setState((s) => ({
-        ...s,
-        anchor: next.popupAnchor,
-        entries: s.entries.map((e) => (e.workspaceId === workspaceId ? { ...e, commands } : e)),
-      }))
-      setError(null)
-    } catch (e) {
-      setError(e instanceof Error ? e.message : String(e))
-      // Re-sync to server truth on failure.
-      void load()
-    }
-  }
-
-  /** Compute the next command list for a workspace, THEN save + update state. */
-  const mutateCommands = (workspaceId: string, next: (current: CommandDraft[]) => CommandDraft[]): void => {
-    const entry = state.entries.find((e) => e.workspaceId === workspaceId)
-    if (entry === undefined) return
-    const commands = next(entry.commands)
-    // Optimistic update first (row stays visible immediately), then persist.
-    setState((s) => ({
-      ...s,
-      entries: s.entries.map((e) => (e.workspaceId === workspaceId ? { ...e, commands } : e)),
-    }))
-    void saveCommands(workspaceId, commands)
-  }
-
-  const patchEntry = (workspaceId: string, index: number, field: 'name' | 'command', value: string): void => {
-    mutateCommands(workspaceId, (current) =>
-      current.map((c, i) => (i === index ? { ...c, [field]: value } : c)),
-    )
-  }
-
-  const addCommand = (workspaceId: string): void => {
-    mutateCommands(workspaceId, (current) => [...current, { name: '', command: '' }])
-  }
-
-  const removeCommand = (workspaceId: string, index: number): void => {
-    mutateCommands(workspaceId, (current) => current.filter((_, i) => i !== index))
-  }
-
-  const setAnchor = async (anchor: QuickCommandsSettings['popupAnchor']): Promise<void> => {
-    setState((s) => ({ ...s, anchor }))
-    try {
-      const next = await quickApi.settingsSetAnchor(anchor)
-      setState((s) => ({ ...s, anchor: next.popupAnchor }))
-    } catch (e) {
-      setError(e instanceof Error ? e.message : String(e))
-      void load()
-    }
-  }
-
-  const title = t('cardTitle')
-  const description = t('cardDescription')
-
-  return (
-    <li className={'qc-settings-card' + (open ? ' qc-settings-card-open' : '')}>
-      <button
-        type="button"
-        className="qc-settings-header"
-        aria-expanded={open}
-        aria-label={`${t('collapseOrExpand')}: ${title}`}
-        onClick={() => setOpen((v) => !v)}
-      >
-        <span className="qc-settings-head-text">
-          <span className="qc-settings-name">{title}</span>
-          <span className="qc-settings-description">{description}</span>
-        </span>
-        <IconChevronDownOutline14 className={'qc-settings-chevron' + (open ? ' qc-settings-chevron-open' : '')} />
-      </button>
-
-      {open && (
-        <div className="qc-settings-body">
-          <p className="qc-settings-intro">{t('cardIntro')}</p>
-
-          <div className="qc-settings-anchor">
-            <span className="qc-settings-anchor-label">{t('cardAnchor')}</span>
-            <label className="qc-settings-radio">
-              <input
-                type="radio"
-                name="qc-anchor"
-                checked={state.anchor === 'corner'}
-                onChange={() => void setAnchor('corner')}
-              />
-              {t('cardAnchorCorner')}
-            </label>
-            <label className="qc-settings-radio">
-              <input
-                type="radio"
-                name="qc-anchor"
-                checked={state.anchor === 'button'}
-                onChange={() => void setAnchor('button')}
-              />
-              {t('cardAnchorButton')}
-            </label>
-          </div>
-
-          {error !== null && <div className="qc-settings-error">{t('cardSaveError')}: {error}</div>}
-
-          {state.loaded && state.entries.length === 0 && (
-            <p className="qc-settings-empty">{t('cardNoWorkspaces')}</p>
-          )}
-
-          {state.entries.map((entry) => (
-            <section key={entry.workspaceId} className="qc-settings-workspace">
-              <header className="qc-settings-workspace-head">
-                <span className="qc-settings-workspace-title">{entry.title || entry.path || entry.workspaceId}</span>
-                <span className="qc-settings-workspace-path">{entry.path}</span>
-              </header>
-              {entry.commands.length === 0 && (
-                <p className="qc-settings-no-commands">{t('cardNoCommands')}</p>
-              )}
-              {entry.commands.map((command, index) => (
-                <div key={`${entry.workspaceId}-${index}`} className="qc-settings-command">
-                  <input
-                    className="qc-settings-field qc-settings-field-name"
-                    placeholder={t('cardName')}
-                    value={command.name}
-                    aria-label={t('cardName')}
-                    onChange={(e) => patchEntry(entry.workspaceId, index, 'name', e.target.value)}
-                  />
-                  <input
-                    className="qc-settings-field qc-settings-field-command"
-                    placeholder={t('cardCommand')}
-                    value={command.command}
-                    aria-label={t('cardCommand')}
-                    onChange={(e) => patchEntry(entry.workspaceId, index, 'command', e.target.value)}
-                  />
-                  <button
-                    type="button"
-                    className="qc-settings-icon-btn"
-                    aria-label={t('cardRemove')}
-                    title={t('cardRemove')}
-                    onClick={() => removeCommand(entry.workspaceId, index)}
-                  >
-                    <IconTrashOutline16 size={14} />
-                  </button>
-                </div>
-              ))}
-              <button type="button" className="qc-settings-add-btn" onClick={() => addCommand(entry.workspaceId)}>
-                <IconPlusOutline16 size={14} />
-                {t('cardAddCommand')}
-              </button>
-            </section>
-          ))}
-        </div>
-      )}
-    </li>
-  )
-}