dsh-deferred-boot 0.3.1 → 0.3.2

package/market/index.json

@@ -35,8 +35,8 @@
       },
       "versions": [
         {
-          "version": "0.3.1",
-          "publishTimestamp": 1794052210,
+          "version": "0.3.2",
+          "publishTimestamp": 1794054744,
           "source": {
             "type": "npm"
           },

package/package.json

@@ -1,71 +1,71 @@
-{
-  "name": "dsh-deferred-boot",
-  "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"
-}
+{
+  "name": "dsh-deferred-boot",
+  "version": "0.3.2",
+  "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/src/index.js

@@ -8,10 +8,39 @@
 // `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'
+import { appendFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { createDeferredBoot, probeReadySource } from './scheduler.js'
 
 export const name = 'dsh-deferred-boot'
 
+// Startup trace.
+//
+// `dsh-deferred-boot` is the only plugin that is guaranteed to apply early and
+// that already has a ready probe, which makes it a convenient clock for the
+// host: one line when this plugin applies, one when the host reports ready.
+// The numbers separate "the host took N ms to boot" from "the window took the
+// rest", which is otherwise unmeasurable from inside the process. Written to
+// `~/.dsh/startup-trace.log`; failures are ignored, a trace must never break a
+// boot.
+function traceStartup(ctx, stage, extra) {
+  try {
+    const now = Date.now()
+    const parts = [
+      new Date(now).toISOString(),
+      stage,
+      `process-uptime=${Math.round(process.uptime() * 1000)}ms`,
+    ]
+    const loaderStart = ctx?.loader?.envData?.startTime
+    if (typeof loaderStart === 'number') parts.push(`loader-age=${now - loaderStart}ms`)
+    if (extra) parts.push(extra)
+    appendFileSync(join(homedir(), '.dsh', 'startup-trace.log'), parts.join(' ') + '\n')
+  } catch {
+    // tracing is best-effort
+  }
+}
+
 export const Config = Schema.object({
   idleDelay: Schema.number().default(1200).volatile(),
   disposeTimeout: Schema.number().default(10000).volatile(),
@@ -29,7 +58,34 @@ export const Config = Schema.object({
  * @param {{ idleDelay?: number, disposeTimeout?: number, readyFallbackMs?: number, deferredPlugins?: unknown[] }} [config]
  */
 export function apply(ctx, config = {}) {
+  const applyAt = Date.now()
+  traceStartup(ctx, 'deferred-boot.apply')
   const scheduler = createDeferredBoot(ctx, config, { log: ctx.logger })
+
+  // One poller until the host reports ready, then it stops itself. `unref` so a
+  // lingering timer can never hold the process open.
+  let traceTimer = null
+  const stopTrace = () => {
+    if (traceTimer) clearInterval(traceTimer)
+    traceTimer = null
+  }
+  try {
+    traceTimer = setInterval(() => {
+      const source = probeReadySource(ctx)
+      if (source !== null) {
+        traceStartup(ctx, 'host-ready', `after-apply=${Date.now() - applyAt}ms source=${source}`)
+        stopTrace()
+        return
+      }
+      if (Date.now() - applyAt > 60000) {
+        traceStartup(ctx, 'host-ready-timeout', `after-apply=${Date.now() - applyAt}ms`)
+        stopTrace()
+      }
+    }, 120)
+    if (typeof traceTimer.unref === 'function') traceTimer.unref()
+  } catch {
+    // a timer is optional
+  }
   const api = {
     /** Mount a `manual` target on demand. Resolves when the attempt settled. */
     ensure: (id) => scheduler.ensure(id),
@@ -49,9 +105,15 @@ export function apply(ctx, config = {}) {
   }
 
   if (typeof ctx.effect === 'function') {
-    ctx.effect(() => () => scheduler.stop())
+    ctx.effect(() => () => {
+      stopTrace()
+      scheduler.stop()
+    })
   } else if (typeof ctx.on === 'function') {
-    ctx.on('dispose', () => scheduler.stop())
+    ctx.on('dispose', () => {
+      stopTrace()
+      scheduler.stop()
+    })
   }
 
   // start() only schedules a microtask; apply() itself stays synchronous.

package/src/scheduler.js

@@ -92,10 +92,13 @@ export function scheduleSlice(run) {
 /**
  * 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`
+ * Probe order (first hit wins):
+ *   1. `typertGateway.hasLiveClient()` — a browser page has attached to the RPC
+ *      gateway, which is the real `first screen is live` signal on a Web GUI.
+ *   2. `webApp.getAdvertisedUrl()` — the Web GUI is being served, even when no
+ *      page has attached yet (headless).
+ *   3. `app.ready === true` / `connection.hostDescription` / `connection.host` —
+ *      kept for non-Web hosts; none of them exists on the desktop Web GUI.
  *   4. readyFallbackMs timer, so a missing signal can never stall the queue
  *
  * Never hard-codes a host event name.
@@ -114,26 +117,10 @@ export function waitForReady(ctx, fallbackMs, { pollMs = READY_POLL_MS } = {}) {
     }
 
     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
+      const source = probeReadySource(ctx)
+      if (source === null) return false
+      finish(source)
+      return true
     }
 
     if (probe()) return
@@ -147,6 +134,46 @@ export function waitForReady(ctx, fallbackMs, { pollMs = READY_POLL_MS } = {}) {
   })
 }
 
+/**
+ * Return the name of the first readiness signal that is currently satisfied,
+ * or `null`. Exported so the startup trace can reuse the exact same probe
+ * instead of keeping a second, drifting copy.
+ */
+export function probeReadySource(ctx) {
+  const gateway = readService(ctx, 'typertGateway')
+  if (gateway && typeof gateway.hasLiveClient === 'function') {
+    try {
+      if (gateway.hasLiveClient() === true) return 'typertGateway.hasLiveClient'
+    } catch {
+      // gateway not ready: keep probing
+    }
+  }
+
+  const webApp = readService(ctx, 'webApp')
+  if (webApp && typeof webApp.getAdvertisedUrl === 'function') {
+    try {
+      const url = webApp.getAdvertisedUrl()
+      if (typeof url === 'string' && url.length > 0) return 'webApp.getAdvertisedUrl'
+    } catch {
+      // server not bound yet: keep probing
+    }
+  }
+
+  const app = readService(ctx, 'app')
+  if (app && app.ready === true) return 'app.ready'
+
+  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) return 'connection.hostDescription'
+    const host = connection.host
+    if (host && (host.home || host.name || host.id)) return 'connection.host'
+  }
+
+  return null
+}
+
 function readService(ctx, name) {
   try {
     if (typeof ctx.get === 'function') {
@@ -193,6 +220,17 @@ export function findExistingEntry(loader, target) {
   } catch {
     // resolve() throws for missing ids: expected
   }
+  // A bundle patch may already have inserted this module into the `include`
+  // group, where it lives under the full id `include:<id>`. Creating a root
+  // entry with the short id next to it would be a second copy of the same
+  // module — and a duplicate id as soon as the group prefix is in play.
+  try {
+    if (typeof loader.resolve === 'function') {
+      return loader.resolve(`include:${target.id}`)
+    }
+  } catch {
+    // not nested: expected when the bundle was removed from the profile
+  }
   return null
 }
 
@@ -323,6 +361,32 @@ export function createDeferredBoot(ctx, rawConfig, { log } = {}) {
     return changed
   }
 
+  /**
+   * Mount one entry the way a bundle patch would.
+   *
+   * Bundle patches register their plugins inside the `include` group, and
+   * `loader.create(options, 'include')` is exactly the call that group performs
+   * on its own config, so the deferred entry lands under the familiar
+   * `include:<id>` name and a later bundle re-add hot-updates it in place
+   * instead of leaving a second copy of the same module in the tree.
+   *
+   * The group only exists while a bundle provides `cordis:include`; a
+   * hand-written profile may not have one, so fall back to the root group.
+   * A create that fails *after* inserting still leaves the entry behind, hence
+   * the re-check before the fallback.
+   */
+  async function createMounted(loader, target) {
+    const options = { id: target.id, name: target.name, config: target.config }
+    try {
+      return await loader.create(options, 'include')
+    } catch (error) {
+      const nested = findExistingEntry(loader, target)
+      if (nested) return nested.id
+      logger?.info?.(`dsh-deferred-boot: include group unavailable for ${target.id}: ${describe(error)}`)
+      return await loader.create(options)
+    }
+  }
+
   async function mountOne(target, reason) {
     if (stopped) return
     if (target.state === 'mounted' || target.state === 'disabled' || target.state === 'failed') return
@@ -340,7 +404,7 @@ export function createDeferredBoot(ctx, rawConfig, { log } = {}) {
       return
     }
     try {
-      const id = await loader.create({ id: target.id, name: target.name, config: target.config })
+      const id = await createMounted(loader, target)
       target.handle = loader.store?.[id] ?? findExistingEntry(loader, target)
       target.state = 'mounted'
       logger?.info?.(`dsh-deferred-boot: mounted ${target.id} (${reason})`)