@linxin666/dsh-usage 0.4.2 → 0.4.4

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
 }

package/lib/types/host/run-guarded.d.ts

@@ -1,39 +0,0 @@
-/**
- * Async-boundary guard shared by the plugin family's Host halves: every
- * fire-and-forget promise chain and callback the host runtime does not own
- * (route handlers, timers, event listeners, spawned work) funnels through
- * these helpers. The dsh host installs a process-level fail-loud guard that
- * turns ANY unhandled promise rejection into a whole-process exit — one
- * plugin's stray rejection would otherwise take every plugin down. These
- * helpers exist so that failure mode is structurally impossible in family
- * code: the rejection becomes a logged error at the plugin boundary instead.
- *
- * Complements the aggregate's shell isolation (packages/dsh-web-all): the
- * shell contains import/activation failures at boot; runGuarded contains
- * run-time failures after activation.
- * @module dsh-web-shared/host/run-guarded
- */
-/**
- * Run one async operation, logging (never propagating) a rejection. Use for
- * promises whose lifecycle the caller does not await: spawned work, retry
- * loops, background flushes. Returns the original promise so callers can
- * still chain when they want to.
- * @param promise - the work to shield; any thenable.
- * @param label - log prefix naming the work site.
- * @param log - error sink; defaults to console.error.
- * @returns the input promise (rejection already consumed).
- */
-export declare function runGuarded<T>(promise: PromiseLike<T>, label: string, log?: (error: unknown) => void): PromiseLike<T>;
-/**
- * Wrap one callback so every invocation is individually guarded: a rejection
- * inside one call is logged and swallowed instead of escaping into whatever
- * infrastructure invoked the callback (HTTP server, EventEmitter, interval).
- * Sync throws are caught identically; a returned promise is replaced by
- * `undefined` after guarding (callers that need the original rejection should
- * await inside their own try/catch instead).
- * @param label - log prefix naming the callback site.
- * @param handler - the work to guard.
- * @param log - error sink; defaults to console.error.
- * @returns a wrapped callback with the same parameter list.
- */
-export declare function guardedHandler<A extends unknown[]>(label: string, handler: (...args: A) => unknown, log?: (error: unknown) => void): (...args: A) => unknown;

package/src/host/run-guarded.ts

@@ -1,76 +0,0 @@
-// Generated by scripts/sync-shared.mjs from shared/host/run-guarded.ts. Do not edit this copy; edit the shared source and run "node scripts/sync-shared.mjs".
-/**
- * Async-boundary guard shared by the plugin family's Host halves: every
- * fire-and-forget promise chain and callback the host runtime does not own
- * (route handlers, timers, event listeners, spawned work) funnels through
- * these helpers. The dsh host installs a process-level fail-loud guard that
- * turns ANY unhandled promise rejection into a whole-process exit — one
- * plugin's stray rejection would otherwise take every plugin down. These
- * helpers exist so that failure mode is structurally impossible in family
- * code: the rejection becomes a logged error at the plugin boundary instead.
- *
- * Complements the aggregate's shell isolation (packages/dsh-web-all): the
- * shell contains import/activation failures at boot; runGuarded contains
- * run-time failures after activation.
- * @module dsh-web-shared/host/run-guarded
- */
-
-/** Format one failure line for logging. */
-function formatFailure(label: string, error: unknown): Error {
-  return new Error(`[${label}] unhandled async failure: ${error instanceof Error ? error.stack ?? error.message : String(error)}`)
-}
-
-/**
- * Run one async operation, logging (never propagating) a rejection. Use for
- * promises whose lifecycle the caller does not await: spawned work, retry
- * loops, background flushes. Returns the original promise so callers can
- * still chain when they want to.
- * @param promise - the work to shield; any thenable.
- * @param label - log prefix naming the work site.
- * @param log - error sink; defaults to console.error.
- * @returns the input promise (rejection already consumed).
- */
-export function runGuarded<T>(promise: PromiseLike<T>, label: string, log: (error: unknown) => void = console.error): PromiseLike<T> {
-  void Promise.resolve(promise).catch(error => {
-    log(formatFailure(label, error))
-  })
-  return promise
-}
-
-/**
- * Wrap one callback so every invocation is individually guarded: a rejection
- * inside one call is logged and swallowed instead of escaping into whatever
- * infrastructure invoked the callback (HTTP server, EventEmitter, interval).
- * Sync throws are caught identically; a returned promise is replaced by
- * `undefined` after guarding (callers that need the original rejection should
- * await inside their own try/catch instead).
- * @param label - log prefix naming the callback site.
- * @param handler - the work to guard.
- * @param log - error sink; defaults to console.error.
- * @returns a wrapped callback with the same parameter list.
- */
-export function guardedHandler<A extends unknown[]>(
-  label: string,
-  handler: (...args: A) => unknown,
-  log: (error: unknown) => void = console.error,
-): (...args: A) => unknown {
-  return (...args: A) => {
-    try {
-      const result = handler(...args)
-      if (isPromiseLike(result)) {
-        void Promise.resolve(result).catch(error => {
-          log(formatFailure(label, error))
-        })
-        return undefined
-      }
-      return result
-    } catch (error) {
-      log(formatFailure(label, error))
-      return undefined
-    }
-  }
-}
-
-function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
-  return typeof value === 'object' && value !== null && typeof (value as PromiseLike<unknown>).then === 'function'
-}