@quazardous/qdadm 2.13.0 → 2.15.0

package/src/vite/qdadmDebugPlugin.ts

@@ -34,9 +34,22 @@ interface PendingRequest {
   timeout: ReturnType<typeof setTimeout>
 }
 
+/** Typed page-side queries (#1398) — served by the injected client. */
+export type DebugQueryType =
+  | 'describe'
+  | 'dump'
+  | 'call'
+  | 'sessionInfo'
+  | 'routes'
+  | 'entityState'
+  | 'entityCall'
+  | 'storageDump'
+  | 'bootlog'
+  | 'recentSignals'
+
 interface DebugRequest {
   id: string
-  type: 'describe' | 'dump' | 'call'
+  type: DebugQueryType
   payload?: unknown
   /** Target a specific session (server → client). */
   sessionId?: string
@@ -67,6 +80,26 @@ interface SessionState {
   meta: Record<string, unknown>
 }
 
+/** Broker surface exposed to sibling plugins via `plugin.api` (#1398). */
+export interface QdadmDebugPluginApi {
+  /** Send a typed query to the page and await its reply. */
+  ask: (type: DebugQueryType, payload?: unknown, sessionId?: string) => Promise<unknown>
+  /** Resolve a session param ('latest' or id) to a live session, if any. */
+  pickSession: (
+    sessionParam: string | null
+  ) => { id: string; lastSeenAt: number; meta: Record<string, unknown> } | null
+  listSessions: () => Array<{
+    id: string
+    firstSeenAt: number
+    lastSeenAt: number
+    ageMs: number
+    hasDescribe: boolean
+    hasSnapshot: boolean
+    meta: Record<string, unknown>
+  }>
+  prefix: string
+}
+
 export interface QdadmDebugPluginOptions {
   /** URL prefix (default '/__qdadm') */
   prefix?: string
@@ -203,9 +236,21 @@ export function qdadmDebugPlugin(options: QdadmDebugPluginOptions = {}): Plugin
     return s
   }
 
+  /** Inter-plugin API (#1398) — consumed by @quazardous/qdmcp. */
+  const api: QdadmDebugPluginApi = {
+    ask,
+    pickSession: (sessionParam) => {
+      const s = pickSession(sessionParam)
+      return s ? { id: s.id, lastSeenAt: s.lastSeenAt, meta: s.meta } : null
+    },
+    listSessions,
+    prefix,
+  }
+
   return {
     name: 'qdadm-debug',
     apply: 'serve',
+    api,
 
     transformIndexHtml: {
       order: 'pre',
@@ -294,7 +339,10 @@ export function qdadmDebugPlugin(options: QdadmDebugPluginOptions = {}): Plugin
             res.setHeader('x-qdadm-session', session.id)
             return sendJson(res, 200, data)
           }
-          return sendJson(res, 404, { error: `unknown ${req.method} ${path}` })
+          // Unknown subpath: fall through — sibling plugins (e.g.
+          // @quazardous/qdadm-mcp) mount their own endpoints under the
+          // same prefix (#1398).
+          return next()
         } catch (e) {
           return sendJson(res, 500, { error: (e as Error).message })
         }
@@ -333,6 +381,34 @@ function readBody(req: IncomingMessage): Promise<string> {
  * stays fresh. Listens for ad-hoc requests targeted at this session.
  */
 const HMR_CLIENT_SCRIPT = String.raw`
+// ── Boot capture (#1398): this head module runs BEFORE the app's entry
+// module, so console/window errors from the very first app statement are
+// buffered — visible over MCP even when the app dies before the bridge
+// exists (the class of failure a bridge-only design can never see).
+const __bootAt = Date.now()
+const __bootlog = { errors: [], warns: [], pageErrors: [], rejections: [] }
+function __cap(arr, entry) { arr.push(entry); if (arr.length > 200) arr.shift() }
+function __fmt(args) {
+  try {
+    return Array.from(args).map((a) => {
+      if (a instanceof Error) return a.stack || a.message
+      if (typeof a === 'object') { try { return JSON.stringify(a) } catch (e) { return String(a) } }
+      return String(a)
+    }).join(' ').slice(0, 2000)
+  } catch (e) { return '[unformattable]' }
+}
+const __origError = console.error.bind(console)
+const __origWarn = console.warn.bind(console)
+console.error = function () { __cap(__bootlog.errors, { at: Date.now(), msg: __fmt(arguments) }); __origError.apply(null, arguments) }
+console.warn = function () { __cap(__bootlog.warns, { at: Date.now(), msg: __fmt(arguments) }); __origWarn.apply(null, arguments) }
+window.addEventListener('error', (e) => {
+  __cap(__bootlog.pageErrors, { at: Date.now(), msg: String(e.message || e), source: e.filename ? e.filename + ':' + e.lineno : undefined })
+})
+window.addEventListener('unhandledrejection', (e) => {
+  let msg; try { msg = e.reason && (e.reason.stack || e.reason.message) || String(e.reason) } catch (err) { msg = '[unreadable reason]' }
+  __cap(__bootlog.rejections, { at: Date.now(), msg: String(msg).slice(0, 2000) })
+})
+
 const hot = import.meta.hot
 if (!hot) {
   console.warn('[qdadm-debug] import.meta.hot unavailable in injected script')
@@ -344,6 +420,95 @@ if (!hot) {
 
   const w = /** @type {any} */ (window)
 
+  // Signal ring buffer — armed once __qdadm.signals is reachable.
+  const __signals = []
+  let __signalsArmed = false
+  function __armSignals() {
+    if (__signalsArmed) return
+    const q = w.__qdadm
+    if (!q || !q.signals || typeof q.signals.on !== 'function') return
+    try {
+      q.signals.on('**', (event) => { __cap(__signals, { at: Date.now(), name: event && event.name }) ; if (__signals.length > 100) __signals.shift() })
+      __signalsArmed = true
+    } catch (e) {}
+  }
+
+  function __sessionInfo() {
+    const q = w.__qdadm || {}
+    let app = {}
+    try { app = (q.kernel && q.kernel.options && q.kernel.options.app) || {} } catch (e) {}
+    let route = null
+    try { const r = q.router && q.router.currentRoute && q.router.currentRoute.value; route = r ? { name: r.name, fullPath: r.fullPath } : null } catch (e) {}
+    return {
+      sessionId, bootAt: __bootAt, now: Date.now(), url: location.href,
+      app: { name: app.name, version: typeof app.version === 'function' ? app.version() : app.version },
+      route, bridgeReady: !!bridge, signalsArmed: __signalsArmed,
+      bootlogCounts: { errors: __bootlog.errors.length, warns: __bootlog.warns.length, pageErrors: __bootlog.pageErrors.length, rejections: __bootlog.rejections.length },
+    }
+  }
+
+  function __routes() {
+    const q = w.__qdadm
+    if (!q || !q.router) throw new Error('router not ready')
+    return q.router.getRoutes().map((r) => ({
+      name: r.name, path: r.path,
+      meta: { entity: r.meta && r.meta.entity, layout: r.meta && r.meta.layout, requiresAuth: r.meta && r.meta.requiresAuth, public: r.meta && r.meta.public },
+    }))
+  }
+
+  function __manager(entity) {
+    const q = w.__qdadm
+    if (!q || !q.orchestrator) throw new Error('orchestrator not ready')
+    if (!q.orchestrator.isRegistered(entity)) throw new Error('entity not registered: ' + entity + ' (known: ' + q.orchestrator.getRegisteredNames().join(', ') + ')')
+    return q.orchestrator.get(entity)
+  }
+
+  function __entityState(payload) {
+    const q = w.__qdadm
+    if (!payload || !payload.entity) {
+      return { entities: q && q.orchestrator ? q.orchestrator.getRegisteredNames() : [] }
+    }
+    const m = __manager(payload.entity)
+    const safe = (fn) => { try { return fn() } catch (e) { return '[error: ' + (e && e.message) + ']' } }
+    const fields = {}
+    try {
+      const fs = m.fields || m._fields || {}
+      for (const k in fs) fields[k] = { type: fs[k] && fs[k].type, label: fs[k] && fs[k].label, required: !!(fs[k] && fs[k].required) }
+    } catch (e) {}
+    return {
+      entity: payload.entity,
+      idField: safe(() => m.idField), labelField: safe(() => m.labelField),
+      label: safe(() => m.label), labelPlural: safe(() => m.labelPlural),
+      can: { create: safe(() => m.canCreate()), read: safe(() => m.canRead()), update: safe(() => m.canUpdate()), delete: safe(() => m.canDelete()) },
+      fields,
+      storage: safe(() => { const st = m.storage || m._storage; return st ? { kind: st.constructor && st.constructor.name, storageKey: st._storageKey } : null }),
+    }
+  }
+
+  async function __entityCall(payload) {
+    if (!payload || !payload.entity || !payload.op) throw new Error('entityCall requires { entity, op, ... }')
+    const m = __manager(payload.entity)
+    const op = payload.op
+    if (op === 'list') return await m.list(payload.params || {})
+    if (op === 'get') return await m.get(payload.id)
+    if (op === 'create') return await m.create(payload.data || {})
+    if (op === 'update') return await m.update(payload.id, payload.data || {})
+    if (op === 'delete') { await m.delete(payload.id); return { deleted: payload.id } }
+    throw new Error('unknown op "' + op + '" (list|get|create|update|delete)')
+  }
+
+  function __storageDump(payload) {
+    if (!payload || !payload.entity) throw new Error('storageDump requires { entity }')
+    const m = __manager(payload.entity)
+    const st = m.storage || m._storage
+    const key = st && st._storageKey
+    if (!key) return { storageKey: null, note: 'storage exposes no localStorage key (' + (st && st.constructor && st.constructor.name) + ')' }
+    const raw = localStorage.getItem(key)
+    let parsed = null
+    try { parsed = raw ? JSON.parse(raw) : null } catch (e) { parsed = '[unparsable]' }
+    return { storageKey: key, count: Array.isArray(parsed) ? parsed.length : null, data: parsed }
+  }
+
   function helloIfNeeded() {
     try { hot.send('qdadm:debug:push', { type: 'hello', sessionId, meta }) } catch (e) {}
   }
@@ -365,6 +530,16 @@ if (!hot) {
     if (msg && msg.sessionId && msg.sessionId !== sessionId) return
     const id = (msg && msg.id) || ''
     try {
+      // Typed queries (#1398): bridge-independent — they must answer even
+      // when the app died before the bridge existed.
+      if (msg.type === 'bootlog') { hot.send('qdadm:debug:reply', { id, ok: true, data: __bootlog, sessionId }); return }
+      if (msg.type === 'sessionInfo') { hot.send('qdadm:debug:reply', { id, ok: true, data: __sessionInfo(), sessionId }); return }
+      if (msg.type === 'recentSignals') { __armSignals(); hot.send('qdadm:debug:reply', { id, ok: true, data: { armed: __signalsArmed, events: __signals }, sessionId }); return }
+      if (msg.type === 'routes') { hot.send('qdadm:debug:reply', { id, ok: true, data: __routes(), sessionId }); return }
+      if (msg.type === 'entityState') { hot.send('qdadm:debug:reply', { id, ok: true, data: __entityState(msg.payload), sessionId }); return }
+      if (msg.type === 'entityCall') { const data = await __entityCall(msg.payload); hot.send('qdadm:debug:reply', { id, ok: true, data, sessionId }); return }
+      if (msg.type === 'storageDump') { hot.send('qdadm:debug:reply', { id, ok: true, data: __storageDump(msg.payload), sessionId }); return }
+
       const b = w.__qdadm && w.__qdadm.debug && w.__qdadm.debug.bridge
       if (!b) throw new Error('debug bridge not ready')
       let data
@@ -385,6 +560,7 @@ if (!hot) {
     bridge = w.__qdadm && w.__qdadm.debug && w.__qdadm.debug.bridge
     if (!bridge) return
     clearInterval(attachTimer)
+    __armSignals()
     helloIfNeeded()
     pushDescribe()
     pushSnapshot()

package/src/vite/qdadmPlugin.ts

@@ -23,13 +23,11 @@
  * - `optimizeDeps.exclude` keeps primevue/@primeuix/themes/qdadm out of the
  *   pre-bundle so BOTH pipelines resolve the same raw modules. Excluding
  *   qdadm also keeps HMR sane when the package is consumed via a symlink.
- * - `optimizeDeps.include` pre-bundles qdadm's CJS transitives (currently
- *   `pluralize`), which cannot be served raw as ESM. The list lives HERE —
- *   consumers should not have to track qdadm's internal CJS deps (skybot
- *   feedback on #1389). Both the nested (`@quazardous/qdadm > pluralize`,
- *   npm installs) and plain (`pluralize`, symlinked installs where the
- *   nested path can't resolve) forms are declared; the unused one is a
- *   no-op warning at worst.
+ * - qdadm has NO CJS transitives (pluralize is vendored as ESM, #1454), so
+ *   there is nothing to `optimizeDeps.include` — which also means nothing
+ *   for the optimizer to fail resolving in file:-linked installs where
+ *   npm (install-links=false) never materializes qdadm's deps at the
+ *   consumer root.
  * - When `node_modules/@quazardous/qdadm` is a symlink (file:/workspace
  *   link — qdadm's own dev mode against a testbed app), its realpath is
  *   appended to `server.fs.allow` so qdadm's `?raw` dynamic imports (i18n
@@ -44,9 +42,6 @@ import fs from 'node:fs'
 import path from 'node:path'
 import { searchForWorkspaceRoot, type Plugin, type UserConfig } from 'vite'
 
-/** qdadm's CJS transitive deps that must be pre-bundled (internal knowledge). */
-const CJS_TRANSITIVES = ['pluralize']
-
 export interface QdadmVitePluginOptions {
   /**
    * Extra packages to dedupe on top of the defaults
@@ -84,12 +79,10 @@ export function qdadmVitePlugin(options: QdadmVitePluginOptions = {}): Plugin {
       // Symlinked install (file:/workspace link)? Allow serving from the
       // link target, which typically lives outside the consumer's root.
       const fsAllow: string[] = []
-      let symlinked = false
       try {
         const pkgDir = path.join(root, 'node_modules', '@quazardous', 'qdadm')
         const real = fs.realpathSync(pkgDir)
         if (real !== pkgDir) {
-          symlinked = true
           fsAllow.push(searchForWorkspaceRoot(root), real)
         }
       } catch {
@@ -123,13 +116,6 @@ export function qdadmVitePlugin(options: QdadmVitePluginOptions = {}): Plugin {
         },
         optimizeDeps: {
           exclude: [...widgetExcludes, ...themesExcludes, '@quazardous/qdadm'],
-          // One form per install mode: the nested path resolves through a
-          // real node_modules chain (npm installs), the plain form through a
-          // symlink realpath — declaring the unused one logs a "Failed to
-          // resolve dependency" warning (skybot testbed, #1389).
-          include: symlinked
-            ? [...CJS_TRANSITIVES]
-            : CJS_TRANSITIVES.map((dep) => `@quazardous/qdadm > ${dep}`),
         },
         ...(fsAllow.length > 0 ? { server: { fs: { allow: fsAllow } } } : {}),
       }

package/src/vite-env.d.ts

@@ -32,19 +32,3 @@ declare module '*.sass' {
   const content: string
   export default content
 }
-
-// `pluralize` ships as plain JS without bundled `.d.ts`. The official
-// types live in `@types/pluralize` but pulling them in as a runtime
-// dep here is overkill for a single-call usage. Declare the minimum
-// surface we use so `strict` mode is happy without DefinitelyTyped.
-declare module 'pluralize' {
-  interface PluralizeFn {
-    (word: string, count?: number, inclusive?: boolean): string
-    singular(word: string): string
-    plural(word: string, count?: number, inclusive?: boolean): string
-    isPlural(word: string): boolean
-    isSingular(word: string): boolean
-  }
-  const pluralize: PluralizeFn
-  export default pluralize
-}

package/src/types/pluralize.d.ts

@@ -1,19 +0,0 @@
-/**
- * Type declarations for pluralize module
- */
-declare module 'pluralize' {
-  function pluralize(word: string, count?: number, inclusive?: boolean): string
-
-  namespace pluralize {
-    function plural(word: string): string
-    function singular(word: string): string
-    function isPlural(word: string): boolean
-    function isSingular(word: string): boolean
-    function addPluralRule(rule: string | RegExp, replacement: string): void
-    function addSingularRule(rule: string | RegExp, replacement: string): void
-    function addIrregularRule(single: string, plural: string): void
-    function addUncountableRule(word: string | RegExp): void
-  }
-
-  export = pluralize
-}