@linxin666/dsh-usage 0.4.2 → 0.4.3

package/src/client/settings-entry-form.ts

@@ -0,0 +1,142 @@
+// Generated by scripts/sync-shared.mjs from shared/client/settings/settings-entry-form.ts. Do not edit this copy; edit the shared source and run "node scripts/sync-shared.mjs".
+// Generated by scripts/sync-shared.mjs from shared/client/settings/settings-entry-form.ts. Do not edit this copy; edit the shared source and run "node scripts/sync-shared.mjs".
+/**
+ * Family settings form bound to the profile entry id a Host actually serves.
+ *
+ * Under the 0.1.7 settings model a form is addressed by PROFILE ENTRY ID, while
+ * a family card knows only its own settings namespace. The family binder
+ * (`ctx.get('webUiSettings')`, published by dsh-web-settings) resolves one onto
+ * the other and is the preferred transport; this module is the fallback for a
+ * page that serves no binder — the group plugin is not installed, or its client
+ * half has not applied yet (the aggregate mounts its children in order, and a
+ * child still waiting on its own injects publishes nothing).
+ *
+ * The shared describe mirror is the only local evidence of which row id this
+ * profile serves, but it answers asynchronously: at plugin activation it usually
+ * holds nothing yet. A one-shot guess therefore cannot be right for every
+ * deployment, and the form is bound once per session:
+ *
+ * - binding the bare namespace made every save answer `No configurable plugin
+ *   entry "<namespace>"` on an aggregate install (the namespace is not an entry
+ *   id there), which the card reported as "the deployment did not accept these
+ *   values";
+ * - binding the aggregate row id would break a standalone install, whose row id
+ *   is the namespace or the package's own `ui-*` row.
+ *
+ * So the fallback starts on the most likely row and REBINDS the moment the
+ * mirror names one of this package's rows. Until the mirror answers, the form
+ * reports the binding it holds (usually `loading`), which the card renders as an
+ * unavailable form rather than a doomed one.
+ */
+import type { ConfigForm, ConfigFormSnapshot, ConfigForms } from '@deepseek-ai/dsh-client-ui-settings/client'
+
+/** Options of {@link createServedEntryForm}. */
+export interface ServedEntryFormOptions<T> {
+  /** The shared configuration forms service (`ctx.configForms`). */
+  forms: ConfigForms
+  /**
+   * Profile entry ids this package's rows carry, most likely first: the
+   * aggregate's generated row, the package's own standalone row, then the bare
+   * namespace. The first is the fallback while the mirror has no answer; the
+   * last is the answer when the mirror serves none of them.
+   */
+  entryIds: readonly string[]
+}
+
+/** The snapshot a form reports before the Host has answered with this entry. */
+function pendingSnapshot<T>(): ConfigFormSnapshot<T> {
+  return {
+    status: 'loading',
+    value: undefined,
+    base: undefined,
+    user: undefined,
+    revision: undefined,
+    writable: false,
+    mode: 'host',
+  }
+}
+
+/**
+ * Create a settings form bound to the profile entry id this Host serves, and
+ * rebound whenever the shared describe mirror names a different one of this
+ * package's rows.
+ * @param options - the shared forms service and this package's candidate row ids.
+ * @returns a form delegating to the currently resolved entry's own form.
+ */
+export function createServedEntryForm<T>(options: ServedEntryFormOptions<T>): ConfigForm<T> {
+  const { forms, entryIds } = options
+  const fallbackId = entryIds[0]
+  const namespaceId = entryIds[entryIds.length - 1]
+  const listeners = new Set<() => void>()
+  let boundId: string | undefined
+  let bound: ConfigForm<T> | undefined
+  let offBound: (() => void) | undefined
+  let snapshot: ConfigFormSnapshot<T> = pendingSnapshot<T>()
+
+  /** Republish: the delegated snapshot when one is bound, the pending one otherwise. */
+  const publish = (): void => {
+    if (bound !== undefined) snapshot = bound.getSnapshot()
+    for (const listener of [...listeners]) listener()
+  }
+
+  /**
+   * The entry id the mirror currently justifies. An unanswered or empty mirror
+   * is not evidence of absence, so it keeps the first candidate; a mirror that
+   * answers without any of this package's rows leaves the namespace itself.
+   * @returns the entry id to bind.
+   */
+  const resolve = (): string => {
+    let served: readonly string[] | undefined
+    try {
+      served = forms.describe().getSnapshot().view?.namespaces.map(row => row.ns)
+    } catch {
+      // A mirror that refuses the read is unanswered too, not absent.
+      served = undefined
+    }
+    if (served === undefined || served.length === 0) return fallbackId
+    return entryIds.find(id => served.includes(id)) ?? namespaceId
+  }
+
+  /** Bind (or rebind) the resolved entry's form; a no-op while it is unchanged. */
+  const bind = (): void => {
+    const target = resolve()
+    if (target === boundId) return
+    offBound?.()
+    offBound = undefined
+    let form: ConfigForm<T>
+    try {
+      form = forms.get<T>(target)
+    } catch {
+      // A service that refuses the id stays unbound; the next mirror answer
+      // retries rather than pinning a wrong entry for the session.
+      boundId = undefined
+      return
+    }
+    boundId = target
+    bound = form
+    offBound = form.subscribe(() => { publish() })
+    publish()
+  }
+
+  // The mirror subscription lives for the page: the card owns its form for the
+  // session, and the ConfigForm contract carries no disposer to hang it on. The
+  // callback is cheap (a resolve plus a no-op while the id is unchanged). A
+  // mirror without a subscription seat keeps the initial binding.
+  try {
+    forms.describe().subscribe(() => { bind() })
+  } catch {
+    // A describe face that refuses the subscription: the initial binding stands.
+  }
+  bind()
+
+  return {
+    getSnapshot: () => snapshot,
+    subscribe: (listener) => {
+      listeners.add(listener)
+      return () => { listeners.delete(listener) }
+    },
+    set: (field, value) => bound?.set(field, value) ?? Promise.resolve(false),
+    unset: (field) => bound?.unset(field) ?? Promise.resolve(false),
+    mutate: (ops, expectedRevision) => bound?.mutate(ops, expectedRevision) ?? Promise.resolve(false),
+  }
+}

package/src/index.ts

@@ -1,11 +1,25 @@
 import type { Context } from '@deepseek-ai/cordis'
 import type {} from '@deepseek-ai/dsh-host-webserver'
 import type { SettingsNamespace } from '@deepseek-ai/dsh-settings'
-import z from 'schemastery'
+import z from '@deepseek-ai/schemastery'
 import { mountOnce } from './mount-once.ts'
 import { UsageService, type UsageServiceOptions } from './host/usage-service.ts'
 import { makeUsageOverviewRoute, makeUsageRefreshRoute } from './host/routes.ts'
 
+declare module '@deepseek-ai/cordis' {
+  interface Events {
+    /**
+     * Volatile config values were committed into the running fiber without a
+     * remount; dispatched to the owning fiber only. Spelled here because the
+     * Loader package is not a dependency of this plugin, with the Loader's own
+     * shape so the two declarations merge when a Host program carries both.
+     * @param paths - changed config paths as key arrays; every value is committed before dispatch.
+     * @mode emit
+     */
+    'loader/volatile-update'(paths: readonly (readonly string[])[]): void
+  }
+}
+
 export const name = 'dsh-usage'
 export const inject = ['webServer']
 /**
@@ -16,29 +30,75 @@ export const inject = ['webServer']
  */
 export const USAGE_SETTINGS_NAMESPACE = 'dsh-usage' as SettingsNamespace
 
-export interface Config {
-  enabled?: boolean
+/** The stable reference a `volatile()` config field resolves to; its owner updates it in place. */
+interface ConfigRef<T> {
+  /** @returns the value currently committed for the running instance. */
+  get(): T | undefined
+}
+
+/** One config field as the Host hands it over: a live reference, or a plain value (profile patches, tests). */
+type ConfigField<T> = ConfigRef<T> | T | undefined
+
+/** The config the Host hands this activation — the runtime face of {@link Config}. */
+export interface UsageConfigFields {
+  enabled?: ConfigField<boolean>
   /** Provider probe cycle in seconds; 30-3600. */
-  pollIntervalSec?: number
+  pollIntervalSec?: ConfigField<number>
   /** Ledger retention in local days. */
-  retainDays?: number
+  retainDays?: ConfigField<number>
 }
 
-export const Config: z<Config> = z.object({
-  enabled: z.boolean().default(true),
-  pollIntervalSec: z.number().min(30).max(3600).default(60),
-  retainDays: z.number().min(7).max(730).default(180),
+/**
+ * Plugin config schema. Under the 0.1.7 settings model this schema IS the
+ * entry's settings page: the Host derives one form per profile entry from it
+ * and serves it only when at least one field is `volatile()`. The marker is
+ * also what admits a write and what keeps the edit on the live path — the
+ * Loader commits the new value into the field's reference and announces
+ * `loader/volatile-update` on this fiber instead of remounting the row, so the
+ * probe cycle, its ledger and its route registrations survive a settings save.
+ *
+ * The schema is left to inference rather than annotated with
+ * `z<UsageConfigFields>`: a volatile field's parsed output is a reference while
+ * its accepted input stays the plain value, so the two sides no longer share
+ * one shape and the annotation would reject the schema the Host must be given.
+ */
+export const Config = z.object({
+  enabled: z.boolean().default(true).volatile(),
+  pollIntervalSec: z.number().min(30).max(3600).default(60).volatile(),
+  retainDays: z.number().min(7).max(730).default(180).volatile(),
 })
 
 export interface ResolvedConfig extends UsageServiceOptions {
   enabled: boolean
 }
 
-export function resolveConfig(config?: Config): ResolvedConfig {
+/** Read one config field, following the live reference the schema produces. */
+function readConfigField<T>(field: ConfigField<T>): T | undefined {
+  if (field === undefined) return undefined
+  if (typeof field === 'object' && field !== null && typeof (field as ConfigRef<T>).get === 'function') {
+    return (field as ConfigRef<T>).get()
+  }
+  return field as T
+}
+
+/** Read one numeric field, falling back when the value is absent or not a usable number. */
+function readNumber(field: ConfigField<number>, fallback: number): number {
+  const value = readConfigField(field)
+  return typeof value === 'number' && Number.isFinite(value) ? value : fallback
+}
+
+/**
+ * Resolve the effective settings of one activation. Volatile references are
+ * read here, so every re-arm observes the latest committed values rather than
+ * whatever the row was activated with.
+ * @param config - the config the Host passed to the activation.
+ * @returns the resolved settings.
+ */
+export function resolveConfig(config?: UsageConfigFields): ResolvedConfig {
   return {
-    enabled: config?.enabled ?? true,
-    pollIntervalSec: typeof config?.pollIntervalSec === 'number' ? config.pollIntervalSec : 60,
-    retainDays: typeof config?.retainDays === 'number' ? config.retainDays : 180,
+    enabled: readConfigField(config?.enabled) ?? true,
+    pollIntervalSec: readNumber(config?.pollIntervalSec, 60),
+    retainDays: readNumber(config?.retainDays, 180),
   }
 }
 
@@ -54,31 +114,23 @@ let pendingStop: Promise<unknown> | undefined
 /**
  * Host body. The plugin's own Config schema above is the settings document the
  * 0.1.7 Host serves for this row; the effective config arrives here as the
- * `config` argument the Loader resolved and the Host reloads the row when the
- * user saves a change, so nothing in this body observes or writes settings.
+ * `config` argument, and a settings save re-enters this body through the
+ * volatile path rather than a row reload (see {@link Config}).
  * @param ctx - host root context.
  * @param config - the row's resolved configuration.
  */
-export const apply = mountOnce('@linxin666/dsh-usage', (ctx: Context, config?: Config): void => {
-  const value = resolveConfig(config)
-  // A disabled row mounts nothing: no probe cycle, no ledger, no routes. The
-  // settings page owns the enable switch, and re-enabling reloads this row.
-  if (!value.enabled) return
-
+export const apply = mountOnce('@linxin666/dsh-usage', (ctx: Context, config?: UsageConfigFields): void => {
   let live = true
   let service: UsageService | undefined
   let disposeRoutes: (() => void) | undefined
+  /** True while this activation has a start queued behind a predecessor's flush. */
+  let queued = false
 
-  const begin = (): void => {
-    // The fiber may have gone down while the predecessor's final flush was
-    // still pending; only start while this activation is the live one.
-    if (!live) return
-    const next = new UsageService(ctx, value)
-    service = next
-    next.start()
+  /** Register the service's two routes; the returned disposer unregisters them. */
+  const mountRoutes = (next: UsageService): (() => void) => {
     const disposers = [makeUsageOverviewRoute(ctx, next), makeUsageRefreshRoute(ctx, next)]
       .map((route) => ctx.webServer.register(route))
-    disposeRoutes = () => {
+    return () => {
       for (const dispose of disposers) {
         try {
           dispose()
@@ -89,25 +141,68 @@ export const apply = mountOnce('@linxin666/dsh-usage', (ctx: Context, config?: C
     }
   }
 
-  ctx.effect(() => {
+  /** Start a fresh activation, unless this fiber is down or one already runs. */
+  const launch = (): void => {
+    queued = false
+    if (!live || service !== undefined) return
+    const value = resolveConfig(config)
+    if (!value.enabled) return
+    const next = new UsageService(ctx, value)
+    service = next
+    next.start()
+    disposeRoutes = mountRoutes(next)
+  }
+
+  /** Tear the running activation down, chaining its final flush for any successor. */
+  const stop = (): void => {
+    disposeRoutes?.()
+    disposeRoutes = undefined
+    const stopping = service?.stop()
+    service = undefined
+    if (stopping !== undefined) pendingStop = (pendingStop ?? Promise.resolve()).then(() => stopping)
+  }
+
+  /**
+   * Apply the activation's current settings: a disabled row mounts nothing (no
+   * probe cycle, no ledger, no routes), an enabled one starts on first use and
+   * otherwise re-applies its options in place.
+   */
+  const rearm = (): void => {
+    const value = resolveConfig(config)
+    if (!value.enabled) {
+      queued = false
+      stop()
+      return
+    }
+    if (service !== undefined) {
+      // Retention shrink prunes now; the poll loop reads the new cadence when
+      // its next cycle re-arms.
+      service.applyOptions(value)
+      return
+    }
+    if (queued) return
     if (pendingStop === undefined) {
       // No predecessor's flush is in flight: start now.
-      begin()
-    } else {
-      // Serialize the start behind every predecessor: their final writes must
-      // land on disk before this instance loads the file.
-      pendingStop = pendingStop.then(begin, begin).then(() => undefined)
+      launch()
+      return
     }
+    // Serialize the start behind every predecessor: their final writes must
+    // land on disk before this instance loads the file. `launch` re-reads the
+    // settings, so a disable that arrives while this is queued still wins.
+    queued = true
+    pendingStop = pendingStop.then(launch, launch).then(() => undefined)
+  }
+
+  // The settings write path: the Host committed new values into this row's
+  // volatile references without remounting it, so re-arm from them.
+  ctx.on('loader/volatile-update', () => { rearm() })
+
+  ctx.effect(() => {
+    rearm()
     return () => {
       live = false
-      disposeRoutes?.()
-      disposeRoutes = undefined
-      const stopping = service?.stop()
-      service = undefined
-      // A successor waits for this instance's final flush, which itself waited
-      // for the predecessor's start: a row disposed before it ever started
-      // keeps the earlier link instead of dropping it.
-      if (stopping !== undefined) pendingStop = (pendingStop ?? Promise.resolve()).then(() => stopping)
+      queued = false
+      stop()
     }
   }, 'dsh-usage: runtime')
 })

package/src/mount-once.ts

@@ -5,44 +5,138 @@
  * the loader accepts a standalone install of the same package side by side;
  * without this guard the second instance would still re-register the same
  * webserver routes, tools, settings namespaces, and system-prompt sections
- * and fail the boot. mountOnce makes the second host apply a no-op for the
- * lifetime of the first instance (the browser half is already deduped by
- * package name in the client module host).
+ * and fail the boot. mountOnce makes a mount of an already-mounted package a
+ * no-op for as long as the first instance lives (the browser half is already
+ * deduped by package name in the client module host).
+ *
+ * A no-op is only safe while the holder is ALIVE. The holder can be disposed
+ * long after the refused mount ran its course: the Host reloads a profile by
+ * creating the new loader entries before the old ones are torn down (a
+ * plugin-manager enable/disable/install write, a settings-driven row reload,
+ * HMR), so the new aggregate shell entry mounts its family plugin while the
+ * previous entry still owns the name. Dropping that refused mount lost the
+ * plugin for good - the previous entry then disposed its own mount, releasing
+ * the name with nobody left to take it, and the family row stayed listed as
+ * active while its host routes 404ed (the task-board panel showed
+ * "board.hostError.notMounted", no degraded record appeared, and only a Host
+ * restart recovered it).
+ *
+ * The refused mount is therefore QUEUED, not dropped, and replayed the moment
+ * the holder releases the name - if the waiting fiber is still alive then. The
+ * single-instance guarantee is unchanged: exactly one mount is live per
+ * package name, and the replay re-enters the guard so a later mount still
+ * dedupes against it.
  *
  * The registry rides a global symbol so two module instances of the same
- * package (npm copy vs repository link) still share one verdict. cordis
- * `ctx.effect` runs its callback immediately and treats the callback's
+ * package (npm copy vs repository link) still share one verdict. That symbol
+ * is a CROSS-REPOSITORY contract, not this file's private state: the four
+ * satellite packages (dsh-skins / dsh-pet / dsh-presets /
+ * dsh-community-plugins) are separate repositories carrying their own copy of
+ * this guard, rebuilt on their own schedule, so the value under `MOUNTED`
+ * must keep the shape every published copy reads (a `Set` of package names
+ * with `has`/`add`/`delete`). The wait queues this guard added therefore live
+ * under their own additive key, and the registry reads back a `Set` even when
+ * some other build left a different value there. Changing `MOUNTED`'s shape
+ * in place broke that contract once: a satellite's legacy copy created a
+ * `Set`, the family's new copy read it as a `Map`, and every family row
+ * mounted after it failed with "claims.get is not a function".
+ *
+ * cordis `ctx.effect` runs its callback immediately and treats the callback's
  * return value as the fiber disposer, so the unmarker is returned, not run.
  */
 
+/** Published cross-repository contract: package names currently mounted. */
 const MOUNTED = Symbol.for('dsh-web.mounted-plugins')
 
+/** Additive key this guard owns: refused mounts waiting for the name. */
+const WAITERS = Symbol.for('dsh-web.mounted-plugins.waiters')
+
+/** The slice of a cordis context this guard touches. */
+interface MountContext {
+  effect?: (effect: () => unknown) => unknown
+}
+
+/** One mount that was refused while another fiber owned the package name. */
+interface PendingMount {
+  /** Replay the refused mount; a no-op once its own fiber has been disposed. */
+  run(): void
+}
+
 interface MountRegistry {
-  [MOUNTED]?: Set<string>
+  [MOUNTED]?: unknown
+  [WAITERS]?: Map<string, PendingMount[]>
 }
 
+/**
+ * The shared name registry, always a `Set` whatever another build stored here:
+ * a foreign value (an interim shape, a hand-written global) must not take every
+ * family plugin down with it.
+ * @returns the process-wide set of mounted package names.
+ */
 function mountedSet(): Set<string> {
   const registry = globalThis as MountRegistry
-  return (registry[MOUNTED] ??= new Set())
+  const existing = registry[MOUNTED]
+  if (existing instanceof Set) return existing as Set<string>
+  const created = new Set<string>()
+  registry[MOUNTED] = created
+  return created
+}
+
+/** Queue per package name for mounts refused while a holder was alive. */
+function mountWaiters(): Map<string, PendingMount[]> {
+  const registry = globalThis as MountRegistry
+  return (registry[WAITERS] ??= new Map())
 }
 
 /**
  * Wrap a cordis plugin apply so the package runs at most once per process.
- * The first mount registers normally and unmarks when its fiber disposes;
- * any later mount of the same package name is a no-op.
+ * The first mount registers normally and releases the name when its fiber
+ * disposes; a mount refused while that name is held waits for the release and
+ * then runs, unless its own fiber disposes first.
  * @param packageName - npm package identity shared by every install source.
  * @param fn - the original plugin apply.
  * @returns an apply of the same shape.
  */
 export function mountOnce<T extends (...args: any[]) => unknown>(packageName: string, fn: T): T {
-  return ((...args: unknown[]) => {
+  const mount = (...args: unknown[]): unknown => {
     const mounted = mountedSet()
-    if (mounted.has(packageName)) return
+    const ctx = args[0] as MountContext | undefined
+    if (mounted.has(packageName)) {
+      // Another fiber (the aggregate row, a standalone install, or a copy built
+      // from an older revision of this guard) owns the name. Queue instead of
+      // dropping: dropping lost the plugin for the rest of the process when the
+      // holder was disposed by a reload.
+      const waiters = mountWaiters()
+      const queue = waiters.get(packageName) ?? []
+      let alive = true
+      const pending: PendingMount = {
+        run: () => {
+          if (alive) mount(...args)
+        },
+      }
+      // A fiber that dies while it waits must not be replayed afterwards: its
+      // context is disposed and registering effects on it would throw.
+      ctx?.effect?.(() => () => {
+        alive = false
+        const index = queue.indexOf(pending)
+        if (index >= 0) queue.splice(index, 1)
+      })
+      queue.push(pending)
+      waiters.set(packageName, queue)
+      return
+    }
     mounted.add(packageName)
-    const ctx = args[0] as { effect?: (effect: () => unknown) => unknown } | undefined
     ctx?.effect?.(() => () => {
       mounted.delete(packageName)
+      const waiters = mountWaiters()
+      const queue = waiters.get(packageName)
+      if (queue === undefined) return
+      waiters.delete(packageName)
+      // Defer the handover one microtask so the disposing mount's own effects
+      // (routes, ledger, timers) are torn down before the next one registers.
+      for (const waiter of queue.splice(0)) queueMicrotask(() => { waiter.run() })
     })
     return fn(...args)
-  }) as T
+  }
+  return mount as T
 }