@mantiq/heartbeat 0.5.22 → 0.5.23

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mantiq/heartbeat",
-  "version": "0.5.22",
+  "version": "0.5.23",
   "description": "Observability, APM & queue monitoring for MantiqJS",
   "type": "module",
   "license": "MIT",

package/src/Heartbeat.ts

@@ -1,5 +1,5 @@
 import type { HeartbeatConfig } from './contracts/HeartbeatConfig.ts'
-import type { EntryType, PendingEntry } from './contracts/Entry.ts'
+import type { EntryType, PendingEntry, OriginType } from './contracts/Entry.ts'
 import type { Watcher } from './contracts/Watcher.ts'
 import { HeartbeatStore } from './storage/HeartbeatStore.ts'
 import { RecordHeartbeatEntries } from './jobs/RecordHeartbeatEntries.ts'
@@ -52,6 +52,11 @@ export class Heartbeat {
     return this.watchers
   }
 
+  /** Count buffered entries of a given type (for widget stats before flush). */
+  getBufferedCount(type: EntryType): number {
+    return this.buffer.filter((e) => e.type === type).length
+  }
+
   // ── Entry Recording ─────────────────────────────────────────────────────
 
   /**
@@ -69,6 +74,8 @@ export class Heartbeat {
       content,
       tags,
       requestId: this._tracer?.currentRequestId() ?? null,
+      originType: this._tracer?.currentOriginType() ?? 'standalone',
+      originId: this._tracer?.currentRequestId() ?? null,
       createdAt: Date.now(),
     }
 
@@ -94,33 +101,14 @@ export class Heartbeat {
       this.flushTimer = null
     }
 
-    // Check if queue system is available — if not, write directly (async, fire-and-forget)
-    let queueAvailable = false
-    try {
-      const { getQueueManager } = require('@mantiq/queue')
-      getQueueManager() // throws if not initialized
-      queueAvailable = true
-    } catch {
-      // Queue not available
-    }
-
-    if (queueAvailable) {
-      try {
-        const { dispatch } = require('@mantiq/queue')
-        dispatch(new RecordHeartbeatEntries(entries))
-          .onQueue(this.config.queue.queue)
-          .onConnection(this.config.queue.connection)
-          .send()
-          .catch(() => {
-            this.store.insertEntries(entries).catch(() => { /* swallow */ })
-          })
-      } catch {
-        this.store.insertEntries(entries).catch(() => { /* swallow */ })
+    // Write directly to the dedicated heartbeat SQLite database.
+    // The queue adds unnecessary latency for telemetry — heartbeat has its
+    // own isolated connection so writes don't block the main app database.
+    this.store.insertEntries(entries).catch((e) => {
+      if (process.env.APP_DEBUG === 'true') {
+        console.error('[Heartbeat] Failed to persist entries:', (e as Error)?.message ?? e)
       }
-    } else {
-      // Direct write — async fire-and-forget fallback
-      this.store.insertEntries(entries).catch(() => { /* swallow */ })
-    }
+    })
   }
 
   // ── Pruning ─────────────────────────────────────────────────────────────

package/src/HeartbeatServiceProvider.ts

@@ -21,6 +21,7 @@ import { ModelWatcher } from './watchers/ModelWatcher.ts'
 import { LogWatcher } from './watchers/LogWatcher.ts'
 import { MailWatcher } from './watchers/MailWatcher.ts'
 import { ScheduleWatcher } from './watchers/ScheduleWatcher.ts'
+import { CommandWatcher } from './watchers/CommandWatcher.ts'
 import { CreateHeartbeatTables } from './migrations/CreateHeartbeatTables.ts'
 import { DashboardController } from './dashboard/DashboardController.ts'
 import { HeartbeatMiddleware } from './middleware/HeartbeatMiddleware.ts'
@@ -114,6 +115,9 @@ export class HeartbeatServiceProvider extends ServiceProvider {
       this.registerMiddleware(heartbeat, tracer, requestWatcher, metrics)
     } catch { /* HttpKernel not available */ }
 
+    // Wire external package hooks (CLI, logging, mail)
+    this.wireExternalWatchers(heartbeat, tracer)
+
     // Register dashboard routes
     if (config.dashboard.enabled) {
       try {
@@ -220,6 +224,7 @@ export class HeartbeatServiceProvider extends ServiceProvider {
       ['log', new LogWatcher()],
       ['mail', new MailWatcher()],
       ['schedule', new ScheduleWatcher()],
+      ['command', new CommandWatcher()],
     ]
 
     const on = eventBus.on.bind(eventBus)
@@ -240,4 +245,65 @@ export class HeartbeatServiceProvider extends ServiceProvider {
 
     return requestWatcher
   }
+
+  /**
+   * Wire the CLI command kernel to record command executions.
+   * Sets a static hook on @mantiq/cli Kernel so every command run
+   * creates a trace context and records a 'command' entry.
+   */
+  private wireExternalWatchers(heartbeat: Heartbeat, tracer: Tracer): void {
+    // ── CLI commands ──────────────────────────────────────────────────────
+    try {
+      const { Kernel } = require('@mantiq/cli')
+      const commandWatcher = heartbeat.getWatchers().find((w) => w instanceof CommandWatcher) as CommandWatcher | undefined
+      if (commandWatcher) {
+        Kernel._onCommandExecuted = (data: { name: string; args: Record<string, any>; exitCode: number; duration: number }) => {
+          const commandId = crypto.randomUUID()
+          tracer.startCommand(commandId)
+          commandWatcher.recordCommand({
+            name: data.name,
+            arguments: data.args,
+            options: {},
+            exit_code: data.exitCode,
+            duration: data.duration,
+            output: null,
+          })
+          heartbeat.flush()
+          tracer.endCommand()
+        }
+      }
+    } catch { /* @mantiq/cli not installed */ }
+
+    // ── Logging ───────────────────────────────────────────────────────────
+    try {
+      const { LogManager } = require('@mantiq/logging')
+      const logWatcher = heartbeat.getWatchers().find((w) => w instanceof LogWatcher) as LogWatcher | undefined
+      if (logWatcher) {
+        LogManager._onLog = (level: string, message: string, context: Record<string, any>, channel: string) => {
+          logWatcher.recordLog(level, message, context, channel)
+        }
+      }
+    } catch { /* @mantiq/logging not installed */ }
+
+    // ── Mail ──────────────────────────────────────────────────────────────
+    try {
+      const { MailManager } = require('@mantiq/mail')
+      const mailWatcher = heartbeat.getWatchers().find((w) => w instanceof MailWatcher) as MailWatcher | undefined
+      if (mailWatcher) {
+        MailManager._onMailSent = (data: { to: string[]; subject: string; mailer: string; duration: number; queued: boolean }) => {
+          mailWatcher.recordMail({
+            to: data.to,
+            subject: data.subject,
+            from: '',
+            mailer: data.mailer,
+            html: null,
+            text: null,
+            attachments: [],
+            duration: data.duration,
+            queued: data.queued,
+          })
+        }
+      }
+    } catch { /* @mantiq/mail not installed */ }
+  }
 }

package/src/contracts/Entry.ts

@@ -12,6 +12,9 @@ export type EntryType =
   | 'log'
   | 'schedule'
   | 'mail'
+  | 'command'
+
+export type OriginType = 'request' | 'command' | 'schedule' | 'job' | 'standalone'
 
 /**
  * A raw pending entry before it's persisted — pushed by watchers into the buffer.
@@ -21,6 +24,8 @@ export interface PendingEntry {
   content: Record<string, any>
   tags?: string[] | undefined
   requestId: string | null
+  originType: OriginType
+  originId: string | null
   createdAt: number
 }
 
@@ -32,6 +37,8 @@ export interface HeartbeatEntry {
   uuid: string
   type: EntryType
   request_id: string | null
+  origin_type: string
+  origin_id: string | null
   content: string
   tags: string
   created_at: number
@@ -103,6 +110,8 @@ export interface JobEntryContent {
 export interface EventEntryContent {
   event_class: string
   listeners_count: number
+  payload: Record<string, any> | null
+  listeners: string[]
 }
 
 export interface ModelEntryContent {
@@ -124,6 +133,16 @@ export interface ScheduleEntryContent {
   expression: string
   duration: number
   status: 'success' | 'error'
+  output: string | null
+}
+
+export interface CommandEntryContent {
+  name: string
+  arguments: Record<string, any>
+  options: Record<string, any>
+  exit_code: number
+  duration: number
+  output: string | null
 }
 
 export interface MailEntryContent {

package/src/contracts/HeartbeatConfig.ts

@@ -24,6 +24,7 @@ export interface HeartbeatConfig {
     log: { enabled: boolean; level: string }
     schedule: { enabled: boolean }
     mail: { enabled: boolean }
+    command: { enabled: boolean }
   }
   tracing: { enabled: boolean; propagate: boolean }
   sampling: { rate: number; always_sample_errors: boolean }
@@ -57,6 +58,7 @@ export const DEFAULT_CONFIG: HeartbeatConfig = {
     log:       { enabled: true, level: 'debug' },
     schedule:  { enabled: true },
     mail:      { enabled: true },
+    command:   { enabled: true },
   },
   tracing: { enabled: true, propagate: true },
   sampling: { rate: 1.0, always_sample_errors: true },

package/src/dashboard/DashboardController.ts

@@ -11,6 +11,12 @@ import { renderPerformancePage } from './pages/PerformancePage.ts'
 import { renderRequestDetailPage } from './pages/RequestDetailPage.ts'
 import { renderMailPage } from './pages/MailPage.ts'
 import { renderMailDetailPage } from './pages/MailDetailPage.ts'
+import { renderLogsPage } from './pages/LogsPage.ts'
+import { renderModelsPage } from './pages/ModelsPage.ts'
+import { renderSchedulesPage } from './pages/SchedulesPage.ts'
+import { renderCommandsPage } from './pages/CommandsPage.ts'
+import { renderCommandDetailPage } from './pages/CommandDetailPage.ts'
+import { renderNotificationsPage } from './pages/NotificationsPage.ts'
 import type { EntryType } from '../contracts/Entry.ts'
 
 /**
@@ -40,39 +46,49 @@ export class DashboardController {
 
     // API endpoints
     if (sub.startsWith('api/')) {
-      return this.handleApi(sub.slice(4), url.searchParams)
+      return this.handleApi(sub.slice(4), url.searchParams, request.method)
     }
 
     // Page routes
-    const html = await this.renderPage(sub)
+    const html = await this.renderPage(sub, url.searchParams)
     return new Response(html, {
       status: 200,
       headers: { 'Content-Type': 'text/html; charset=utf-8' },
     })
   }
 
-  private async renderPage(sub: string): Promise<string> {
+  private async renderPage(sub: string, searchParams?: URLSearchParams): Promise<string> {
     // Static page routes
     switch (sub) {
       case '':
       case 'overview':
         return renderOverviewPage(this.store, this.metrics, this.basePath)
       case 'requests':
-        return renderRequestsPage(this.store, this.basePath)
+        return renderRequestsPage(this.store, this.basePath, searchParams)
       case 'queries':
-        return renderQueriesPage(this.store, this.basePath)
+        return renderQueriesPage(this.store, this.basePath, searchParams)
       case 'exceptions':
-        return renderExceptionsPage(this.store, this.basePath)
+        return renderExceptionsPage(this.store, this.basePath, searchParams)
       case 'jobs':
-        return renderJobsPage(this.store, this.basePath)
+        return renderJobsPage(this.store, this.basePath, searchParams)
       case 'cache':
-        return renderCachePage(this.store, this.basePath)
+        return renderCachePage(this.store, this.basePath, searchParams)
       case 'events':
-        return renderEventsPage(this.store, this.basePath)
+        return renderEventsPage(this.store, this.basePath, searchParams)
       case 'performance':
-        return renderPerformancePage(this.metrics, this.basePath)
+        return renderPerformancePage(this.store, this.metrics, this.basePath, searchParams)
       case 'mail':
         return renderMailPage(this.store, this.basePath)
+      case 'logs':
+        return renderLogsPage(this.store, this.basePath, searchParams)
+      case 'models':
+        return renderModelsPage(this.store, this.basePath, searchParams)
+      case 'schedules':
+        return renderSchedulesPage(this.store, this.basePath, searchParams)
+      case 'commands':
+        return renderCommandsPage(this.store, this.basePath, searchParams)
+      case 'notifications':
+        return renderNotificationsPage(this.store, this.basePath, searchParams)
     }
 
     // Parameterized routes
@@ -88,12 +104,18 @@ export class DashboardController {
       return html ?? this.render404()
     }
 
+    const commandDetail = sub.match(/^commands\/([a-f0-9-]+)$/)
+    if (commandDetail) {
+      const html = await renderCommandDetailPage(this.store, commandDetail[1]!, this.basePath)
+      return html ?? this.render404()
+    }
+
     return this.render404()
   }
 
   // ── API Endpoints ─────────────────────────────────────────────────────
 
-  private async handleApi(sub: string, params: URLSearchParams): Promise<Response> {
+  private async handleApi(sub: string, params: URLSearchParams, method: string): Promise<Response> {
     try {
       switch (sub) {
         case 'entries':
@@ -102,8 +124,31 @@ export class DashboardController {
           return this.apiMetrics()
         case 'exception-groups':
           return this.apiExceptionGroups()
-        default:
+        case 'exception-groups/resolve':
+          if (method === 'POST') return this.apiResolveExceptionGroup(params)
+          return Response.json({ error: 'Method not allowed' }, { status: 405 })
+        case 'exception-groups/unresolve':
+          if (method === 'POST') return this.apiUnresolveExceptionGroup(params)
+          return Response.json({ error: 'Method not allowed' }, { status: 405 })
+        default: {
+          // Handle parameterized API routes: exceptions/{fingerprint}/resolve|unresolve
+          const exceptionAction = sub.match(/^exceptions\/([^/]+)\/(resolve|unresolve)$/)
+          if (exceptionAction) {
+            const fingerprint = decodeURIComponent(exceptionAction[1]!)
+            const action = exceptionAction[2]!
+            if (action === 'resolve') {
+              await this.store.resolveExceptionGroup(fingerprint)
+            } else {
+              await this.store.unresolveExceptionGroup(fingerprint)
+            }
+            // Redirect back to exceptions page
+            return new Response(null, {
+              status: 302,
+              headers: { Location: `${this.basePath}/exceptions` },
+            })
+          }
           return Response.json({ error: 'Not found' }, { status: 404 })
+        }
       }
     } catch (error) {
       return Response.json({ error: 'Internal error' }, { status: 500 })
@@ -161,6 +206,20 @@ export class DashboardController {
     return Response.json({ data: groups })
   }
 
+  private async apiResolveExceptionGroup(params: URLSearchParams): Promise<Response> {
+    const fingerprint = params.get('fingerprint')
+    if (!fingerprint) return Response.json({ error: 'Missing fingerprint' }, { status: 400 })
+    await this.store.resolveExceptionGroup(fingerprint)
+    return Response.json({ success: true })
+  }
+
+  private async apiUnresolveExceptionGroup(params: URLSearchParams): Promise<Response> {
+    const fingerprint = params.get('fingerprint')
+    if (!fingerprint) return Response.json({ error: 'Missing fingerprint' }, { status: 400 })
+    await this.store.unresolveExceptionGroup(fingerprint)
+    return Response.json({ success: true })
+  }
+
   private render404(): string {
     return `<!DOCTYPE html><html><body><h1>404 — Page not found</h1><p><a href="${this.basePath}">Back to Heartbeat</a></p></body></html>`
   }

package/src/dashboard/pages/CachePage.ts

@@ -1,13 +1,31 @@
 import { renderLayout } from '../shared/layout.ts'
-import { table, badge, timeAgo, escapeHtml, truncate, stat } from '../shared/components.ts'
+import { table, badge, timeAgo, escapeHtml, truncate, stat, filterBar, pagination } from '../shared/components.ts'
 import type { HeartbeatStore } from '../../storage/HeartbeatStore.ts'
 import type { CacheEntryContent } from '../../contracts/Entry.ts'
 
-export async function renderCachePage(store: HeartbeatStore, basePath: string): Promise<string> {
-  const entries = await store.getEntries({ type: 'cache', limit: 100 })
+const PER_PAGE = 50
 
+export async function renderCachePage(store: HeartbeatStore, basePath: string, searchParams?: URLSearchParams): Promise<string> {
+  const page = parseInt(searchParams?.get('page') ?? '1')
+  const operationFilter = searchParams?.get('operation') ?? ''
+  const keySearch = searchParams?.get('search') ?? ''
+
+  // Fetch all cache entries for stats + filtering
+  const allEntries = await store.getEntries({ type: 'cache', limit: 5000 })
+
+  // Apply filters in-memory
+  const filtered = allEntries.filter((e) => {
+    const c = JSON.parse(e.content) as CacheEntryContent
+    if (operationFilter && c.operation !== operationFilter) return false
+    if (keySearch && !c.key.toLowerCase().includes(keySearch.toLowerCase())) return false
+    return true
+  })
+
+  const total = filtered.length
+
+  // Compute stats from all entries (not just filtered) for overall hit rate
   let hits = 0, misses = 0, writes = 0, forgets = 0
-  for (const e of entries) {
+  for (const e of allEntries) {
     const op = (JSON.parse(e.content) as CacheEntryContent).operation
     if (op === 'hit') hits++
     else if (op === 'miss') misses++
@@ -17,7 +35,10 @@ export async function renderCachePage(store: HeartbeatStore, basePath: string):
 
   const hitRate = hits + misses > 0 ? ((hits / (hits + misses)) * 100).toFixed(0) + '%' : '--'
 
-  const rows = entries.map((entry) => {
+  // Paginate filtered entries
+  const pageEntries = filtered.slice((page - 1) * PER_PAGE, page * PER_PAGE)
+
+  const rows = pageEntries.map((entry) => {
     const c = JSON.parse(entry.content) as CacheEntryContent
     const v = c.operation === 'hit' ? 'green' : c.operation === 'miss' ? 'amber' : c.operation === 'write' ? 'blue' : 'mute'
     return [
@@ -28,7 +49,34 @@ export async function renderCachePage(store: HeartbeatStore, basePath: string):
     ]
   })
 
+  // Build extra params for pagination
+  const extraParams: Record<string, string> = {}
+  if (operationFilter) extraParams['operation'] = operationFilter
+  if (keySearch) extraParams['search'] = keySearch
+
+  const filters = filterBar({
+    action: `${basePath}/cache`,
+    searchPlaceholder: 'Search key...',
+    searchValue: keySearch,
+    filters: [
+      {
+        name: 'operation',
+        label: 'Operation',
+        options: [
+          { value: 'hit', label: 'Hit' },
+          { value: 'miss', label: 'Miss' },
+          { value: 'write', label: 'Write' },
+          { value: 'forget', label: 'Forget' },
+        ],
+        selected: operationFilter,
+      },
+    ],
+  })
+
+  const paginationBase = buildPaginationUrl(`${basePath}/cache`, extraParams)
+
   const content = `
+    ${filters}
     <div class="stats">
       ${stat('Hit Rate', hitRate, `${hits} hits / ${misses} misses`)}
       ${stat('Hits', hits.toString())}
@@ -38,7 +86,15 @@ export async function renderCachePage(store: HeartbeatStore, basePath: string):
     <div class="card">
       ${table(['Operation', 'Key', 'Store', 'Time'], rows)}
     </div>
+    ${pagination(total, page, PER_PAGE, paginationBase)}
   `
 
   return renderLayout({ title: 'Cache', activePage: 'cache', basePath, content })
 }
+
+function buildPaginationUrl(base: string, params: Record<string, string>): string {
+  const entries = Object.entries(params).filter(([, v]) => v)
+  if (entries.length === 0) return base
+  const qs = entries.map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`).join('&')
+  return `${base}?${qs}`
+}