@strav/devtools 0.1.0

package/README.md

@@ -0,0 +1,64 @@
+# @stravigor/devtools
+
+Debug inspector and performance monitor for the [Strav](https://www.npmjs.com/package/@stravigor/core) framework. Request inspector, SQL query profiler, exception tracker, log viewer, and APM dashboard.
+
+## Install
+
+```bash
+bun add -d @stravigor/devtools
+bun strav install devtools
+```
+
+Requires `@stravigor/core` as a peer dependency.
+
+## Setup
+
+```ts
+import { DevtoolsProvider } from '@stravigor/devtools'
+
+app.use(new DevtoolsProvider())
+```
+
+The provider auto-registers the middleware and serves the dashboard at `/_devtools`.
+
+## Collectors
+
+Collectors capture data from your application:
+
+- **RequestCollector** — HTTP requests and responses
+- **QueryCollector** — SQL queries with timing
+- **ExceptionCollector** — Unhandled exceptions
+- **LogCollector** — Log entries
+- **JobCollector** — Queue job execution
+
+## Recorders
+
+Recorders aggregate data for performance monitoring:
+
+- **SlowRequestsRecorder** — Tracks slow HTTP requests
+- **SlowQueriesRecorder** — Tracks slow SQL queries
+
+## Usage
+
+```ts
+import { devtools } from '@stravigor/devtools'
+
+// Access collector data programmatically
+const entries = await devtools.entries({ type: 'request', limit: 50 })
+const aggregates = await devtools.aggregates('slow-requests', '1h')
+```
+
+## CLI
+
+```bash
+bun strav devtools:setup    # Create the devtools tables
+bun strav devtools:prune    # Clean up old entries
+```
+
+## Documentation
+
+See the full [Devtools guide](../../guides/devtools.md).
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@strav/devtools",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Debug inspector and performance monitor for the Strav framework",
+  "license": "MIT",
+  "exports": {
+    ".": "./src/index.ts",
+    "./*": "./src/*.ts"
+  },
+  "strav": {
+    "commands": "src/commands"
+  },
+  "files": [
+    "src/",
+    "stubs/",
+    "package.json",
+    "tsconfig.json"
+  ],
+  "peerDependencies": {
+    "@strav/kernel": "0.1.0",
+    "@strav/http": "0.1.0",
+    "@strav/database": "0.1.0",
+    "@strav/cli": "0.1.0"
+  },
+  "scripts": {
+    "test": "bun test tests/",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "commander": "^14.0.3"
+  }
+}

package/src/collectors/collector.ts

@@ -0,0 +1,65 @@
+import type { DevtoolsEntry, EntryType, CollectorOptions } from '../types.ts'
+import type EntryStore from '../storage/entry_store.ts'
+
+/**
+ * Base class for all collectors (the Telescope-like component).
+ *
+ * A collector listens to framework events and produces {@link DevtoolsEntry}
+ * objects that are flushed to the {@link EntryStore} in batches.
+ */
+export default abstract class Collector {
+  protected enabled: boolean
+  protected queue: DevtoolsEntry[] = []
+
+  constructor(
+    protected store: EntryStore,
+    protected options: CollectorOptions
+  ) {
+    this.enabled = options.enabled !== false
+  }
+
+  /** Register event listeners. Called once during DevtoolsManager boot. */
+  abstract register(): void
+
+  /** Remove event listeners. Called during teardown. */
+  abstract teardown(): void
+
+  /** Flush buffered entries to the store. */
+  async flush(): Promise<void> {
+    if (this.queue.length === 0) return
+    const batch = this.queue.splice(0)
+    try {
+      await this.store.store(batch)
+    } catch {
+      // Devtools must never crash the app
+    }
+  }
+
+  /** Create an entry and buffer it for storage. */
+  protected record(
+    type: EntryType,
+    batchId: string,
+    content: Record<string, unknown>,
+    tags: string[] = [],
+    familyHash: string | null = null
+  ): void {
+    if (!this.enabled) return
+
+    this.queue.push({
+      uuid: crypto.randomUUID(),
+      batchId,
+      type,
+      familyHash,
+      content,
+      tags,
+      createdAt: new Date(),
+    })
+  }
+
+  /** Generate a simple hash for grouping similar entries (e.g. same SQL pattern). */
+  protected hash(input: string): string {
+    const hasher = new Bun.CryptoHasher('md5')
+    hasher.update(input)
+    return hasher.digest('hex')
+  }
+}

package/src/collectors/exception_collector.ts

@@ -0,0 +1,56 @@
+import { Emitter } from '@stravigor/kernel'
+import type { Listener } from '@stravigor/kernel'
+import Collector from './collector.ts'
+import type EntryStore from '../storage/entry_store.ts'
+import type { CollectorOptions } from '../types.ts'
+
+/**
+ * Captures exceptions emitted by the ExceptionHandler.
+ *
+ * Listens to the `http:error` event added to the core ExceptionHandler.
+ * Records exception class, message, stack trace, and request context.
+ */
+export default class ExceptionCollector extends Collector {
+  private listener: Listener | null = null
+  private getBatchId: () => string
+
+  constructor(store: EntryStore, options: CollectorOptions, getBatchId: () => string) {
+    super(store, options)
+    this.getBatchId = getBatchId
+  }
+
+  register(): void {
+    if (!this.enabled) return
+
+    this.listener = (payload: { error: Error; ctx?: { path?: string; method?: string } }) => {
+      const { error, ctx } = payload
+      const batchId = this.getBatchId()
+
+      const content: Record<string, unknown> = {
+        class: error.constructor.name,
+        message: error.message,
+        stack: error.stack?.split('\n').slice(0, 20),
+      }
+
+      if (ctx) {
+        content.method = ctx.method
+        content.path = ctx.path
+      }
+
+      const tags = [error.constructor.name]
+      const familyHash = this.hash(`${error.constructor.name}:${error.message}`)
+
+      this.record('exception', batchId, content, tags, familyHash)
+      this.flush()
+    }
+
+    Emitter.on('http:error', this.listener)
+  }
+
+  teardown(): void {
+    if (this.listener) {
+      Emitter.off('http:error', this.listener)
+      this.listener = null
+    }
+  }
+}

package/src/collectors/job_collector.ts

@@ -0,0 +1,119 @@
+import { Emitter } from '@stravigor/kernel'
+import type { Listener } from '@stravigor/kernel'
+import Collector from './collector.ts'
+import type EntryStore from '../storage/entry_store.ts'
+import type { CollectorOptions } from '../types.ts'
+
+/**
+ * Captures queue job lifecycle events.
+ *
+ * Listens to:
+ * - `queue:dispatched` — when a job is pushed onto the queue
+ * - `queue:processed` — when a job completes successfully
+ * - `queue:failed` — when a job fails after max attempts
+ */
+export default class JobCollector extends Collector {
+  private dispatchedListener: Listener | null = null
+  private processedListener: Listener | null = null
+  private failedListener: Listener | null = null
+  private getBatchId: () => string
+
+  constructor(store: EntryStore, options: CollectorOptions, getBatchId: () => string) {
+    super(store, options)
+    this.getBatchId = getBatchId
+  }
+
+  register(): void {
+    if (!this.enabled) return
+
+    this.dispatchedListener = (payload: {
+      id: number
+      name: string
+      queue: string
+      payload: unknown
+    }) => {
+      const batchId = this.getBatchId()
+
+      this.record(
+        'job',
+        batchId,
+        {
+          status: 'dispatched',
+          jobId: payload.id,
+          name: payload.name,
+          queue: payload.queue,
+          payload: payload.payload,
+        },
+        [payload.name, 'dispatched']
+      )
+      this.flush()
+    }
+
+    this.processedListener = (payload: {
+      job: string
+      id: number
+      queue: string
+      duration: number
+    }) => {
+      const batchId = this.getBatchId()
+
+      this.record(
+        'job',
+        batchId,
+        {
+          status: 'processed',
+          jobId: payload.id,
+          name: payload.job,
+          queue: payload.queue,
+          duration: Math.round(payload.duration * 100) / 100,
+        },
+        [payload.job, 'processed']
+      )
+      this.flush()
+    }
+
+    this.failedListener = (payload: {
+      job: string
+      id: number
+      queue: string
+      error: string
+      duration: number
+    }) => {
+      const batchId = this.getBatchId()
+
+      this.record(
+        'job',
+        batchId,
+        {
+          status: 'failed',
+          jobId: payload.id,
+          name: payload.job,
+          queue: payload.queue,
+          error: payload.error,
+          duration: Math.round(payload.duration * 100) / 100,
+        },
+        [payload.job, 'failed']
+      )
+      this.flush()
+    }
+
+    Emitter.on('queue:dispatched', this.dispatchedListener)
+    Emitter.on('queue:processed', this.processedListener)
+    Emitter.on('queue:failed', this.failedListener)
+  }
+
+  teardown(): void {
+    if (this.dispatchedListener) {
+      Emitter.off('queue:dispatched', this.dispatchedListener)
+      this.dispatchedListener = null
+    }
+    if (this.processedListener) {
+      Emitter.off('queue:processed', this.processedListener)
+      this.processedListener = null
+    }
+    if (this.failedListener) {
+      Emitter.off('queue:failed', this.failedListener)
+      this.failedListener = null
+    }
+  }
+}

package/src/collectors/log_collector.ts

@@ -0,0 +1,69 @@
+import { Emitter } from '@stravigor/kernel'
+import type { Listener } from '@stravigor/kernel'
+import Collector from './collector.ts'
+import type EntryStore from '../storage/entry_store.ts'
+import type { CollectorOptions } from '../types.ts'
+
+const LOG_LEVELS = ['trace', 'debug', 'info', 'warn', 'error', 'fatal'] as const
+
+interface LogCollectorOptions extends CollectorOptions {
+  level?: string
+}
+
+/**
+ * Captures log entries emitted by the Logger.
+ *
+ * Listens to the `log:entry` event added to the core Logger.
+ * Filters by minimum log level (default: 'debug').
+ */
+export default class LogCollector extends Collector {
+  private listener: Listener | null = null
+  private minLevelIndex: number
+  private getBatchId: () => string
+
+  constructor(store: EntryStore, options: LogCollectorOptions, getBatchId: () => string) {
+    super(store, options)
+    const level = options.level ?? 'debug'
+    this.minLevelIndex = LOG_LEVELS.indexOf(level as (typeof LOG_LEVELS)[number])
+    if (this.minLevelIndex === -1) this.minLevelIndex = 1 // default to debug
+    this.getBatchId = getBatchId
+  }
+
+  register(): void {
+    if (!this.enabled) return
+
+    this.listener = (payload: {
+      level: string
+      msg: string
+      context?: Record<string, unknown>
+    }) => {
+      const levelIndex = LOG_LEVELS.indexOf(payload.level as (typeof LOG_LEVELS)[number])
+      if (levelIndex < this.minLevelIndex) return
+
+      const batchId = this.getBatchId()
+
+      const content: Record<string, unknown> = {
+        level: payload.level,
+        message: payload.msg,
+      }
+
+      if (payload.context) {
+        content.context = payload.context
+      }
+
+      const tags = [payload.level]
+      if (levelIndex >= 4) tags.push('error')
+
+      this.record('log', batchId, content, tags)
+    }
+
+    Emitter.on('log:entry', this.listener)
+  }
+
+  teardown(): void {
+    if (this.listener) {
+      Emitter.off('log:entry', this.listener)
+      this.listener = null
+    }
+  }
+}

package/src/collectors/query_collector.ts

@@ -0,0 +1,106 @@
+import type { SQL } from 'bun'
+import Collector from './collector.ts'
+import DevtoolsManager from '../devtools_manager.ts'
+import type EntryStore from '../storage/entry_store.ts'
+import type { CollectorOptions } from '../types.ts'
+
+interface QueryCollectorOptions extends CollectorOptions {
+  slow?: number
+}
+
+/**
+ * Captures SQL queries by proxying the Bun.sql tagged template call.
+ *
+ * When enabled, wraps the SQL connection with a Proxy that intercepts
+ * tagged template literal calls to record query text, duration, and bindings.
+ */
+export default class QueryCollector extends Collector {
+  private slowThreshold: number
+  private originalSql: SQL | null = null
+  private getBatchId: () => string
+
+  constructor(store: EntryStore, options: QueryCollectorOptions, getBatchId: () => string) {
+    super(store, options)
+    this.slowThreshold = options.slow ?? 100
+    this.getBatchId = getBatchId
+  }
+
+  register(): void {
+    // Proxying is handled by installProxy()
+  }
+
+  teardown(): void {
+    // Proxy removal is handled by DevtoolsManager
+  }
+
+  /**
+   * Wrap a SQL connection with a Proxy that intercepts queries.
+   * Returns the proxied SQL instance.
+   */
+  installProxy(sql: SQL): SQL {
+    if (!this.enabled) return sql
+    this.originalSql = sql
+
+    const collector = this
+
+    return new Proxy(sql, {
+      apply(target, thisArg, args) {
+        // Tagged template calls pass an array of strings as the first argument
+        if (!Array.isArray(args[0])) {
+          return Reflect.apply(target, thisArg, args)
+        }
+
+        const strings = args[0] as string[]
+        const bindings = Array.prototype.slice.call(args, 1)
+
+        // Build a normalized SQL string for hashing (replace values with $N)
+        const sqlText = strings.reduce((acc: string, str: string, i: number) => {
+          return i === 0 ? str : `${acc}$${i}${str}`
+        }, '')
+
+        const start = performance.now()
+        const result = Reflect.apply(target, thisArg, args)
+
+        // Handle async results (most queries return promises)
+        if (result && typeof result.then === 'function') {
+          return result.then((res: unknown) => {
+            collector.recordQuery(sqlText, bindings, performance.now() - start)
+            return res
+          })
+        }
+
+        collector.recordQuery(sqlText, bindings, performance.now() - start)
+        return result
+      },
+    }) as SQL
+  }
+
+  /** Get the original (unwrapped) SQL connection. */
+  getOriginalSql(): SQL | null {
+    return this.originalSql
+  }
+
+  private recordQuery(sql: string, bindings: unknown[], duration: number): void {
+    const batchId = this.getBatchId()
+    const durationRounded = Math.round(duration * 100) / 100
+
+    const tags: string[] = []
+    if (duration >= this.slowThreshold) tags.push('slow')
+
+    // Exclude devtools' own queries
+    if (sql.includes('_strav_devtools_')) return
+
+    const content: Record<string, unknown> = {
+      sql,
+      duration: durationRounded,
+      bindings: bindings.length > 0 ? bindings : undefined,
+      slow: duration >= this.slowThreshold,
+    }
+
+    const familyHash = this.hash(sql)
+    this.record('query', batchId, content, tags, familyHash)
+
+    // Emit for recorders (slow queries aggregation)
+    DevtoolsManager.emitQuery({ sql, duration: durationRounded })
+  }
+}

package/src/collectors/request_collector.ts

@@ -0,0 +1,125 @@
+import type { Context, Middleware, Next } from '@stravigor/http'
+import Collector from './collector.ts'
+import DevtoolsManager from '../devtools_manager.ts'
+import type EntryStore from '../storage/entry_store.ts'
+import type { CollectorOptions } from '../types.ts'
+
+interface RequestCollectorOptions extends CollectorOptions {
+  sizeLimit?: number
+}
+
+/**
+ * Captures HTTP request/response data as devtools entries.
+ *
+ * Unlike other collectors that listen to Emitter events, this one is a
+ * **middleware** — it wraps the request lifecycle to capture timing, headers,
+ * body, and response status.
+ *
+ * @example
+ * import { devtools } from '@stravigor/devtools'
+ * router.use(devtools.middleware())
+ */
+export default class RequestCollector extends Collector {
+  private sizeLimit: number
+
+  constructor(store: EntryStore, options: RequestCollectorOptions) {
+    super(store, options)
+    this.sizeLimit = (options.sizeLimit ?? 64) * 1024 // KB → bytes
+  }
+
+  register(): void {
+    // No-op — request collection uses middleware, not Emitter
+  }
+
+  teardown(): void {
+    // No-op
+  }
+
+  /**
+   * Returns a middleware that records request and response data.
+   * The batchId is set on the context so other collectors (query, cache, etc.)
+   * can correlate their entries to this request.
+   */
+  middleware(): Middleware {
+    const collector = this
+
+    return async (ctx: Context, next: Next): Promise<Response> => {
+      if (!collector.enabled) return next()
+
+      const batchId = crypto.randomUUID()
+      ctx.set('_devtools_batch_id', batchId)
+      DevtoolsManager.setBatchId(batchId)
+
+      const start = performance.now()
+      let response: Response
+      let error: Error | undefined
+
+      try {
+        response = await next()
+      } catch (err) {
+        error = err instanceof Error ? err : new Error(String(err))
+        throw err
+      } finally {
+        const duration = performance.now() - start
+
+        const content: Record<string, unknown> = {
+          method: ctx.method,
+          path: ctx.path,
+          url: ctx.url.toString(),
+          status: error ? 500 : (response!?.status ?? 500),
+          duration: Math.round(duration * 100) / 100,
+          ip: ctx.header('x-forwarded-for') ?? ctx.header('x-real-ip') ?? 'unknown',
+          memory: Math.round((process.memoryUsage.rss() / 1024 / 1024) * 100) / 100,
+        }
+
+        // Request headers (redact sensitive ones)
+        const requestHeaders: Record<string, string> = {}
+        ctx.headers.forEach((value, key) => {
+          if (key === 'authorization' || key === 'cookie') {
+            requestHeaders[key] = '********'
+          } else {
+            requestHeaders[key] = value
+          }
+        })
+        content.requestHeaders = requestHeaders
+
+        // Response headers
+        if (response!) {
+          const responseHeaders: Record<string, string> = {}
+          response.headers.forEach((value, key) => {
+            responseHeaders[key] = value
+          })
+          content.responseHeaders = responseHeaders
+          content.status = response.status
+        }
+
+        if (error) {
+          content.error = error.message
+        }
+
+        const tags: string[] = []
+        tags.push(`status:${content.status}`)
+        if (duration > 1000) tags.push('slow')
+
+        // Tag authenticated user if present
+        const user = ctx.get<{ id?: unknown }>('user')
+        if (user?.id) tags.push(`user:${user.id}`)
+
+        collector.record('request', batchId, content, tags)
+
+        // Emit for recorders (slow requests aggregation)
+        DevtoolsManager.emitRequest({
+          path: ctx.path,
+          method: ctx.method,
+          duration: Math.round(duration * 100) / 100,
+          status: (content.status as number) ?? 500,
+        })
+
+        // Flush immediately — one request = one flush
+        collector.flush()
+      }
+
+      return response!
+    }
+  }
+}

package/src/commands/devtools_prune.ts

@@ -0,0 +1,55 @@
+import type { Command } from 'commander'
+import chalk from 'chalk'
+import { bootstrap, shutdown } from '@stravigor/cli'
+import DevtoolsManager from '../devtools_manager.ts'
+
+export function register(program: Command): void {
+  program
+    .command('devtools:prune')
+    .description('Prune old devtools entries and aggregates')
+    .option('--hours <hours>', 'Delete entries older than this many hours', '24')
+    .action(async (options: { hours: string }) => {
+      let db
+      try {
+        const { db: database, config } = await bootstrap()
+        db = database
+
+        new DevtoolsManager(db, config)
+
+        const hours = parseInt(options.hours, 10)
+        console.log(chalk.dim(`Pruning entries older than ${hours} hours...`))
+
+        const entries = await DevtoolsManager.entryStore.prune(hours)
+        const aggregates = await DevtoolsManager.aggregateStore.prune(hours)
+
+        console.log(chalk.green(`Pruned ${entries} entries and ${aggregates} aggregates.`))
+      } catch (err) {
+        console.error(chalk.red(`Error: ${err instanceof Error ? err.message : err}`))
+        process.exit(1)
+      } finally {
+        if (db) await shutdown(db)
+      }
+    })
+
+  program
+    .command('devtools:setup')
+    .description('Create the devtools storage tables')
+    .action(async () => {
+      let db
+      try {
+        const { db: database, config } = await bootstrap()
+        db = database
+
+        new DevtoolsManager(db, config)
+
+        console.log(chalk.dim('Creating devtools tables...'))
+        await DevtoolsManager.ensureTables()
+        console.log(chalk.green('Devtools tables created successfully.'))
+      } catch (err) {
+        console.error(chalk.red(`Error: ${err instanceof Error ? err.message : err}`))
+        process.exit(1)
+      } finally {
+        if (db) await shutdown(db)
+      }
+    })
+}