dsh-deferred-boot 0.0.0-stage → 0.3.1

package/package.json

@@ -1,6 +1,71 @@
 {
   "name": "dsh-deferred-boot",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.1",
+  "description": "Mount deferred plugins after the main UI is ready, one idle slice at a time",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./scheduler": "./src/scheduler.js",
+    "./client": "./lib/client.js",
+    "./icon": "./icon.svg",
+    "./locale/*.json": "./locale/*.json",
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "icon": "./icon.svg",
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-settings",
+        "@deepseek-ai/dsh-client-ui-plugin-manager",
+        "@deepseek-ai/dsh-api-remotes"
+      ],
+      "platform": "web"
+    }
+  },
+  "files": [
+    "src",
+    "lib",
+    "locale",
+    "docs",
+    "market",
+    "scripts",
+    "cordis.patch.yml",
+    "icon.svg",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "cordis",
+    "startup",
+    "lazy-loading",
+    "deferred",
+    "plugin-manager"
+  ],
+  "author": "BuSheng",
+  "engines": {
+    "dsh": ">=0.2.0-rc.1",
+    "node": ">=20"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "~4.1.0"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.5"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "pack": "powershell -NoProfile -ExecutionPolicy Bypass -File pack.ps1",
+    "index": "node scripts/gen-market-index.mjs"
+  },
+  "license": "MIT"
+}

package/scripts/gen-market-index.mjs

@@ -0,0 +1,55 @@
+// Generate the plugin market index (format 1) for this plugin.
+//
+//   node scripts/gen-market-index.mjs [--index-url https://example.com/market/index.json]
+//
+// The output is `market/index.json`. Host it anywhere that serves HTTPS; users
+// add that URL as an index source in 插件 → 发现 → 添加索引源.
+// The icon is inlined as a data: URL so the JSON is self-contained.
+import { readFile, mkdir, writeFile } from 'node:fs/promises'
+import { fileURLToPath } from 'node:url'
+import { dirname, join } from 'node:path'
+
+const root = join(dirname(fileURLToPath(import.meta.url)), '..')
+const read = async (rel) => readFile(join(root, rel), 'utf8')
+
+const pkg = JSON.parse(await read('package.json'))
+const zh = JSON.parse(await read('locale/zh.json'))
+const en = JSON.parse(await read('locale/en.json'))
+const icon = await read('icon.svg')
+
+const iconDataUrl = `data:image/svg+xml;base64,${Buffer.from(icon, 'utf8').toString('base64')}`
+const args = process.argv.slice(2)
+const indexUrlFlag = args.indexOf('--index-url')
+const indexUrl = indexUrlFlag >= 0 ? args[indexUrlFlag + 1] : 'https://example.com/dsh-deferred-boot/index.json'
+
+const title = { en: en.meta?.title ?? 'Deferred Boot', zh: zh.meta?.title ?? '延迟启动' }
+const description = { en: en.meta?.description ?? '', zh: zh.meta?.description ?? '' }
+
+const index = {
+  format: 1,
+  title,
+  description: { en: 'Plugins that defer heavy plugins until the main UI is ready', zh: '把指定插件推迟到主界面就绪之后再挂载的启动调度插件' },
+  plugins: [
+    {
+      name: pkg.name,
+      title,
+      description,
+      icon: iconDataUrl,
+      author: pkg.author,
+      metadata: { keywords: pkg.keywords ?? [] },
+      versions: [
+        {
+          version: pkg.version,
+          publishTimestamp: Math.floor(Date.now() / 1000),
+          source: { type: 'npm' },
+          engines: { dsh: pkg.engines?.dsh ?? '>=0.2.0-rc.1' },
+        },
+      ],
+    },
+  ],
+}
+
+await mkdir(join(root, 'market'), { recursive: true })
+await writeFile(join(root, 'market', 'index.json'), `${JSON.stringify(index, null, 2)}\n`)
+console.log(`wrote market/index.json for ${pkg.name}@${pkg.version}`)
+console.log(`host it as a static file, then use its URL as an index source: ${indexUrl}`)

package/src/index.js

@@ -0,0 +1,60 @@
+// dsh-deferred-boot — host-side entry.
+//
+// apply() must stay synchronous and cheap: register the scheduler, hand it to
+// the context, and return. No I/O, no imports of target plugins, no awaits.
+//
+// The Config fields are declared `.volatile()` so the settings service exposes
+// an editable form for them. The profile's plugin page renders that form under
+// `plugins.bundle.config` (see lib/client.js), and saving writes the values into
+// the profile patch — the user never edits cordis.patch.yml by hand.
+import Schema from '@deepseek-ai/schemastery'
+import { createDeferredBoot } from './scheduler.js'
+
+export const name = 'dsh-deferred-boot'
+
+export const Config = Schema.object({
+  idleDelay: Schema.number().default(1200).volatile(),
+  disposeTimeout: Schema.number().default(10000).volatile(),
+  readyFallbackMs: Schema.number().default(5000).volatile(),
+  deferredPlugins: Schema.array(Schema.object({
+    id: Schema.string().required(),
+    name: Schema.string().required(),
+    strategy: Schema.string().default('manual'),
+    config: Schema.any().default({}),
+  })).default([]).volatile(),
+})
+
+/**
+ * @param {import('@deepseek-ai/cordis').Context} ctx
+ * @param {{ idleDelay?: number, disposeTimeout?: number, readyFallbackMs?: number, deferredPlugins?: unknown[] }} [config]
+ */
+export function apply(ctx, config = {}) {
+  const scheduler = createDeferredBoot(ctx, config, { log: ctx.logger })
+  const api = {
+    /** Mount a `manual` target on demand. Resolves when the attempt settled. */
+    ensure: (id) => scheduler.ensure(id),
+    /** Snapshot of every target: { id, strategy, state, attempts, lastError }. */
+    status: () => scheduler.status(),
+    /** Dispose one mounted target with the configured timeout. */
+    unmount: (id) => scheduler.unmount(id),
+  }
+  // Cordis 4 contexts are strict proxies: assigning an unknown property throws
+  // `cannot set property "..." without provide`. Register the service through
+  // ctx.provide() so the fiber owns it and disposes it on unload; older Cordis
+  // builds without provide() accept the plain assignment.
+  if (typeof ctx.provide === 'function') {
+    ctx.provide('deferredBoot', api)
+  } else {
+    ctx.deferredBoot = api
+  }
+
+  if (typeof ctx.effect === 'function') {
+    ctx.effect(() => () => scheduler.stop())
+  } else if (typeof ctx.on === 'function') {
+    ctx.on('dispose', () => scheduler.stop())
+  }
+
+  // start() only schedules a microtask; apply() itself stays synchronous.
+  scheduler.start()
+  return api
+}

package/src/scheduler.js

@@ -0,0 +1,419 @@
+// dsh-deferred-boot scheduler core.
+//
+// Responsibilities:
+//   - wait for a "main UI ready" signal with layered fallbacks
+//   - mount deferred targets one at a time, on idle slices (never a whole batch
+//     inside one idle callback)
+//   - check loader existence before every create() (duplicate ids are fatal)
+//   - isolate per-target failures; freeze after repeated failures
+//   - race dispose() against a hard timeout, never leave an unhandled rejection
+//
+// The module is runtime-neutral: it never imports Node or browser globals at
+// load time, only probes them when a schedule is requested.
+
+export const DEFAULT_CONFIG = {
+  idleDelay: 1200,
+  disposeTimeout: 10000,
+  readyFallbackMs: 5000,
+  deferredPlugins: [],
+}
+
+const STRATEGIES = new Set(['idle', 'manual', 'inline-lazy', 'disabled'])
+const MAX_ATTEMPTS = 3
+const READY_POLL_MS = 150
+
+/**
+ * Schemastery's `.volatile()` fields arrive as references with get()/set()
+ * instead of plain values. Unwrap them so the scheduler always sees data.
+ */
+function unwrap(value) {
+  if (value && typeof value === 'object' && typeof value.get === 'function') {
+    try {
+      return value.get()
+    } catch {
+      return value
+    }
+  }
+  return value
+}
+
+function numberOr(value, fallback) {
+  const number = Number(unwrap(value))
+  return Number.isFinite(number) && number >= 0 ? number : fallback
+}
+
+/**
+ * Normalize the user config. Unknown strategies fall back to `manual` so a typo
+ * can never make a heavy plugin mount automatically.
+ */
+export function normalizeConfig(raw) {
+  const source = raw ?? {}
+  const plugins = unwrap(source.deferredPlugins)
+  const config = {
+    idleDelay: numberOr(source.idleDelay, DEFAULT_CONFIG.idleDelay),
+    disposeTimeout: numberOr(source.disposeTimeout, DEFAULT_CONFIG.disposeTimeout),
+    readyFallbackMs: numberOr(source.readyFallbackMs, DEFAULT_CONFIG.readyFallbackMs),
+    deferredPlugins: Array.isArray(plugins) ? plugins : DEFAULT_CONFIG.deferredPlugins,
+  }
+  config.deferredPlugins = config.deferredPlugins.map((item, index) => {
+    const strategy = STRATEGIES.has(item.strategy) ? item.strategy : 'manual'
+    const id = String(item.id ?? item.name ?? `deferred-${index}`)
+    return {
+      id,
+      name: String(item.name ?? id),
+      config: item.config ?? {},
+      strategy,
+      attempts: 0,
+      state: 'pending',
+      lastError: null,
+      handle: null,
+    }
+  })
+  return config
+}
+
+/** Turn one idle task trigger into a callback. Never runs a batch. */
+export function scheduleSlice(run) {
+  const g = globalThis
+  if (g.scheduler && typeof g.scheduler.postTask === 'function') {
+    // background priority: the browser may run it after user-visible work.
+    g.scheduler.postTask(() => run(), { priority: 'background' }).catch(() => {})
+    return
+  }
+  if (typeof g.requestIdleCallback === 'function') {
+    g.requestIdleCallback(() => run(), { timeout: 1000 })
+    return
+  }
+  // Node (host runtime) has neither API. A zero-delay timer keeps the slice
+  // asynchronous and lets the event loop breathe between targets.
+  setTimeout(() => run(), 0)
+}
+
+/**
+ * Wait for the main UI to be ready.
+ *
+ * Probe order:
+ *   1. ctx.connection.hostDescription (string or function)
+ *   2. ctx.connection.host (object with home/name), i.e. the ready handshake
+ *   3. any service exposing a boolean `ready`
+ *   4. readyFallbackMs timer, so a missing signal can never stall the queue
+ *
+ * Never hard-codes a host event name.
+ */
+export function waitForReady(ctx, fallbackMs, { pollMs = READY_POLL_MS } = {}) {
+  return new Promise((resolve) => {
+    let settled = false
+    let timer = null
+    let poll = null
+    const finish = (source) => {
+      if (settled) return
+      settled = true
+      if (timer) clearTimeout(timer)
+      if (poll) clearInterval(poll)
+      resolve(source)
+    }
+
+    const probe = () => {
+      const connection = readService(ctx, 'connection')
+      if (connection) {
+        const description = connection.hostDescription
+        const value = typeof description === 'function' ? description() : description
+        if (typeof value === 'string' && value.length > 0) {
+          finish('connection.hostDescription')
+          return true
+        }
+        const host = connection.host
+        if (host && (host.home || host.name || host.id)) {
+          finish('connection.host')
+          return true
+        }
+      }
+      const app = readService(ctx, 'app') ?? readService(ctx, 'webApp')
+      if (app && app.ready === true) {
+        finish('app.ready')
+        return true
+      }
+      return false
+    }
+
+    if (probe()) return
+
+    timer = setTimeout(() => finish('fallback-timeout'), fallbackMs)
+    poll = setInterval(() => {
+      if (probe()) {
+        // finish() clears the interval itself
+      }
+    }, pollMs)
+  })
+}
+
+function readService(ctx, name) {
+  try {
+    if (typeof ctx.get === 'function') {
+      const service = ctx.get(name)
+      if (service) return service
+    }
+  } catch {
+    // service missing: fall through
+  }
+  try {
+    return ctx[name] ?? null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Look for an entry that already represents `target` in the current loader.
+ * `loader.create` with an existing id replaces/hot-updates rather than adding a
+ * duplicate row, but DSH treats a duplicate entry id in the tree as a hard
+ * startup error, so the check must happen before create().
+ */
+export function findExistingEntry(loader, target) {
+  try {
+    const direct = loader.store?.[target.id]
+    if (direct) return direct
+  } catch {
+    // store is not enumerable in some hosts
+  }
+  try {
+    if (typeof loader.entries === 'function') {
+      for (const entry of loader.entries()) {
+        if (entry?.options?.id === target.id) return entry
+        if (entry?.options?.name === target.name) return entry
+      }
+    }
+  } catch {
+    // entries() may throw while the tree is mutating; treat as absent
+  }
+  try {
+    if (typeof loader.resolve === 'function') {
+      return loader.resolve(target.id)
+    }
+  } catch {
+    // resolve() throws for missing ids: expected
+  }
+  return null
+}
+
+function readFiber(entry) {
+  if (!entry) return null
+  if (entry.fiber && typeof entry.fiber.dispose === 'function') return entry.fiber
+  if (entry.ctx?.fiber && typeof entry.ctx.fiber.dispose === 'function') return entry.ctx.fiber
+  return null
+}
+
+/**
+ * Dispose one mounted target with a hard upper bound.
+ *
+ * Cordis fiber.dispose() resolves only after every async cleanup settles; a
+ * target waiting on a service that never comes back can hang it forever. A
+ * hung dispose holding the mutation lock is what freezes the whole UI, so the
+ * target is removed from the active table *before* the race and a late
+ * rejection gets a sink.
+ */
+export async function disposeWithTimeout(target, loader, timeoutMs, log) {
+  const entry = target.handle ?? findExistingEntry(loader, target)
+  target.handle = null // remove from the active table before awaiting anything
+  const fiber = readFiber(entry)
+  if (!fiber) {
+    try {
+      loader.remove?.(target.id)
+    } catch (error) {
+      log?.warn?.(`dsh-deferred-boot: remove(${target.id}) failed: ${describe(error)}`)
+    }
+    return 'no-fiber'
+  }
+
+  let disposed = false
+  const settle = () => {
+    disposed = true
+  }
+  const disposal = Promise.resolve()
+    .then(() => fiber.dispose())
+    .then(settle, (error) => {
+      settle()
+      log?.warn?.(`dsh-deferred-boot: dispose(${target.id}) rejected: ${describe(error)}`)
+    })
+  // keep a sink on the original promise so a late rejection is never unhandled
+  disposal.catch(() => {})
+
+  const timeout = new Promise((resolve) => setTimeout(resolve, Math.max(1, timeoutMs)))
+  const winner = await Promise.race([
+    disposal.then(() => 'disposed'),
+    timeout.then(() => 'timeout'),
+  ])
+  if (winner === 'timeout' && !disposed) {
+    log?.warn?.(
+      `dsh-deferred-boot: dispose(${target.id}) exceeded ${timeoutMs}ms; continuing without waiting`,
+    )
+  }
+  return winner
+}
+
+export function describe(error) {
+  if (error instanceof Error) return error.message || error.name
+  if (typeof error === 'string') return error
+  try {
+    return JSON.stringify(error)
+  } catch {
+    return String(error)
+  }
+}
+
+/**
+ * Build the scheduler. `apply()` calls this and returns immediately: no I/O,
+ * no awaits, no target imports here.
+ */
+export function createDeferredBoot(ctx, rawConfig, { log } = {}) {
+  const config = normalizeConfig(rawConfig)
+  // Resolve through the service accessor first: a direct ctx.loader read throws
+  // on a context whose inject declaration does not cover the loader service.
+  const loader = readService(ctx, 'loader')
+  const logger = log ?? ctx?.logger
+  const active = new Map()
+  let started = false
+  let readySource = null
+  let stopped = false
+
+  const queue = config.deferredPlugins.filter((t) => t.strategy === 'idle')
+  const manual = new Map(
+    config.deferredPlugins.filter((t) => t.strategy === 'manual').map((t) => [t.id, t]),
+  )
+
+  for (const target of config.deferredPlugins) {
+    if (target.strategy === 'inline-lazy') {
+      logger?.info?.(
+        `dsh-deferred-boot: ${target.id} is inline-lazy; move its heavy work into an idle init inside its own apply() instead of deferring the mount`,
+      )
+    }
+    if (target.strategy === 'disabled') target.state = 'disabled'
+  }
+
+  function status() {
+    if (rebuildFromLoader()) {
+      // state was rebuilt from the live loader after an HMR reload
+    }
+    return config.deferredPlugins.map((t) => ({
+      id: t.id,
+      strategy: t.strategy,
+      state: t.state,
+      attempts: t.attempts,
+      lastError: t.lastError,
+    }))
+  }
+
+  /**
+   * Rebuild mount state from the loader itself, so a scheduler HMR reload does
+   * not mount an already-mounted target twice. Returns true when it changed
+   * anything (used only to keep the call explicit in status()).
+   */
+  function rebuildFromLoader() {
+    if (!loader) return false
+    let changed = false
+    for (const target of config.deferredPlugins) {
+      if (target.state === 'mounted' || target.state === 'disabled') continue
+      const entry = findExistingEntry(loader, target)
+      if (entry) {
+        target.handle = entry
+        target.state = 'mounted'
+        changed = true
+      }
+    }
+    return changed
+  }
+
+  async function mountOne(target, reason) {
+    if (stopped) return
+    if (target.state === 'mounted' || target.state === 'disabled' || target.state === 'failed') return
+    if (target.strategy === 'manual' && reason !== 'ensure') return
+    if (!loader) {
+      target.lastError = 'loader service is unavailable'
+      target.state = 'failed'
+      return
+    }
+    const existing = findExistingEntry(loader, target)
+    if (existing) {
+      target.handle = existing
+      target.state = 'mounted'
+      logger?.info?.(`dsh-deferred-boot: ${target.id} already present; skipped`)
+      return
+    }
+    try {
+      const id = await loader.create({ id: target.id, name: target.name, config: target.config })
+      target.handle = loader.store?.[id] ?? findExistingEntry(loader, target)
+      target.state = 'mounted'
+      logger?.info?.(`dsh-deferred-boot: mounted ${target.id} (${reason})`)
+    } catch (error) {
+      target.attempts += 1
+      target.lastError = describe(error)
+      const fatal = target.attempts >= MAX_ATTEMPTS
+      target.state = fatal ? 'failed' : 'pending'
+      logger?.warn?.(
+        `dsh-deferred-boot: mount(${target.id}) failed (attempt ${target.attempts}${fatal ? ', frozen' : ', will retry'}): ${target.lastError}`,
+      )
+    }
+  }
+
+  function start() {
+    if (started) return
+    started = true
+    if (!queue.length && !manual.size) return
+    // Defer the first probe so apply() stays synchronous and cheap.
+    queueMicrotask(async () => {
+      readySource = await waitForReady(ctx, config.readyFallbackMs)
+      logger?.info?.(`dsh-deferred-boot: ready via ${readySource}`)
+      scheduleSlice(drain)
+    })
+  }
+
+  function drain() {
+    if (stopped) return
+    if (!queue.length) return
+    const target = queue[0]
+    const pending = target.state === 'pending'
+    if (pending && target.attempts < MAX_ATTEMPTS) {
+      mountOne(target, 'idle')
+        .catch((error) => {
+          logger?.warn?.(`dsh-deferred-boot: unexpected mount error: ${describe(error)}`)
+        })
+        .finally(() => {
+          // retry pending target after a failure, but only after idleDelay slices
+          if (target.state === 'pending') {
+            scheduleSlice(drain)
+          } else {
+            queue.shift()
+            scheduleSlice(drain)
+          }
+        })
+      return
+    }
+    // terminal or non-idle: drop and continue the queue
+    queue.shift()
+    scheduleSlice(drain)
+  }
+
+  async function ensure(id) {
+    if (stopped) return
+    const target = manual.get(id) ?? config.deferredPlugins.find((t) => t.id === id)
+    if (!target) {
+      logger?.warn?.(`dsh-deferred-boot: ensure(${id}) unknown target`)
+      return
+    }
+    if (target.state === 'mounted') return
+    await mountOne(target, 'ensure')
+  }
+
+  async function unmount(id) {
+    const target = config.deferredPlugins.find((t) => t.id === id)
+    if (!target || !target.handle) return
+    await disposeWithTimeout(target, loader, config.disposeTimeout, logger)
+    target.state = 'pending'
+  }
+
+  function stop() {
+    stopped = true
+  }
+
+  return { start, status, ensure, unmount, stop, rebuildFromLoader, get config() { return config } }
+}