adonisjs-server-stats 1.6.1 → 1.6.2

package/dist/src/middleware/request_tracking_middleware.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"request_tracking_middleware.d.ts","sourceRoot":"","sources":["../../../src/middleware/request_tracking_middleware.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAA;AACjE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AACpD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AACtD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,2BAA2B,CAAA;AAcvD;;;;GAIG;AACH,wBAAgB,iBAAiB,IAAI,OAAO,CAE3C;AAYD,wBAAgB,aAAa,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,WAAW,KAAK,OAAO,CAAC,GAAG,IAAI,QAEvE;AAOD,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,cAAc,GAAG,IAAI,QAEjE;AAQD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,QAEnD;AASD,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAErD;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAA;IACd,GAAG,EAAE,MAAM,CAAA;IACX,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,CAAC,EAAE,WAAW,CAAA;CACpB;AAQD,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,mBAAmB,KAAK,IAAI,CAAC,GAAG,IAAI,QAEpF;AAED,MAAM,CAAC,OAAO,OAAO,yBAAyB;IACtC,MAAM,CAAC,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM;CA4E5C"}
+{"version":3,"file":"request_tracking_middleware.d.ts","sourceRoot":"","sources":["../../../src/middleware/request_tracking_middleware.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAA;AACjE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AACpD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AACtD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,2BAA2B,CAAA;AAcvD;;;;GAIG;AACH,wBAAgB,iBAAiB,IAAI,OAAO,CAE3C;AAYD,wBAAgB,aAAa,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,WAAW,KAAK,OAAO,CAAC,GAAG,IAAI,QAEvE;AAOD,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,cAAc,GAAG,IAAI,QAEjE;AAQD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,QAEnD;AASD,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAErD;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAA;IACd,GAAG,EAAE,MAAM,CAAA;IACX,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,CAAC,EAAE,WAAW,CAAA;CACpB;AAQD,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,mBAAmB,KAAK,IAAI,CAAC,GAAG,IAAI,QAEpF;AAED,MAAM,CAAC,OAAO,OAAO,yBAAyB;IACtC,MAAM,CAAC,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM;CAoF5C"}

package/dist/src/middleware/request_tracking_middleware.js

@@ -67,7 +67,14 @@ export default class RequestTrackingMiddleware {
             await next();
             return;
         }
+        // Gracefully handle the startup window before collectors initialize.
+        // The provider defers initialization via setImmediate, so early
+        // requests may arrive before httpCollector() has been called.
         const metrics = getRequestMetrics();
+        if (!metrics) {
+            await next();
+            return;
+        }
         const start = performance.now();
         metrics.incrementActiveConnections();
         // Share a lazy shouldShow evaluator with Edge for @serverStats() tag.

package/dist/src/provider/server_stats_provider.d.ts

@@ -14,6 +14,7 @@ export default class ServerStatsProvider {
     private statsController;
     private debugController;
     private apiController;
+    private dashboardDepsAvailable;
     private pinoHookActive;
     private edgePluginActive;
     private prometheusActive;
@@ -23,6 +24,7 @@ export default class ServerStatsProvider {
     private resolvedCollectors;
     constructor(app: ApplicationService);
     boot(): Promise<void>;
+    private initializeBoot;
     /**
      * Read start/kernel.ts and detect auth-related middleware in server.use()
      * or router.use() blocks. Returns import paths of problematic middleware.
@@ -40,6 +42,13 @@ export default class ServerStatsProvider {
      */
     private hookPinoLogger;
     ready(): Promise<void>;
+    private initializeServerStats;
+    /**
+     * Set up the stats collection interval, transmit broadcasting,
+     * and Prometheus integration. Extracted from initializeServerStats
+     * so the ready log fires promptly.
+     */
+    private setupStatsInterval;
     private setupDevToolbar;
     /**
      * Initialize the full-page dashboard: SQLite store, controller,

package/dist/src/provider/server_stats_provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server_stats_provider.d.ts","sourceRoot":"","sources":["../../../src/provider/server_stats_provider.ts"],"names":[],"mappings":"AAyBA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAA;AAQ9D,MAAM,CAAC,OAAO,OAAO,mBAAmB;IAwB1B,SAAS,CAAC,GAAG,EAAE,kBAAkB;IAvB7C,OAAO,CAAC,UAAU,CAA8C;IAChE,OAAO,CAAC,MAAM,CAA2B;IACzC,OAAO,CAAC,UAAU,CAA0B;IAC5C,OAAO,CAAC,cAAc,CAA8B;IACpD,OAAO,CAAC,mBAAmB,CAAmC;IAC9D,OAAO,CAAC,kBAAkB,CAAgC;IAC1D,OAAO,CAAC,uBAAuB,CAA8C;IAC7E,OAAO,CAAC,mBAAmB,CAA6C;IACxE,OAAO,CAAC,WAAW,CAAsB;IACzC,OAAO,CAAC,UAAU,CAA8C;IAChE,OAAO,CAAC,eAAe,CAAqC;IAC5D,OAAO,CAAC,eAAe,CAA+B;IACtD,OAAO,CAAC,aAAa,CAA6B;IAGlD,OAAO,CAAC,cAAc,CAAiB;IACvC,OAAO,CAAC,gBAAgB,CAAiB;IACzC,OAAO,CAAC,gBAAgB,CAAiB;IACzC,OAAO,CAAC,iBAAiB,CAAiB;IAC1C,OAAO,CAAC,gBAAgB,CAAe;IACvC,OAAO,CAAC,cAAc,CAAyC;IAC/D,OAAO,CAAC,kBAAkB,CAAwB;gBAE5B,GAAG,EAAE,kBAAkB;IAEvC,IAAI;IAwGV;;;;;OAKG;IACH,OAAO,CAAC,0BAA0B;IAmDlC;;;;;;;OAOG;YACW,cAAc;IAqCtB,KAAK;YAkIG,eAAe;IAmG7B;;;;;;OAMG;YACW,cAAc;IA0I5B,2DAA2D;IAC3D,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IA2ER,QAAQ;CAwCf"}
+{"version":3,"file":"server_stats_provider.d.ts","sourceRoot":"","sources":["../../../src/provider/server_stats_provider.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAA;AAQ9D,MAAM,CAAC,OAAO,OAAO,mBAAmB;IA2B1B,SAAS,CAAC,GAAG,EAAE,kBAAkB;IA1B7C,OAAO,CAAC,UAAU,CAA8C;IAChE,OAAO,CAAC,MAAM,CAA2B;IACzC,OAAO,CAAC,UAAU,CAA0B;IAC5C,OAAO,CAAC,cAAc,CAA8B;IACpD,OAAO,CAAC,mBAAmB,CAAmC;IAC9D,OAAO,CAAC,kBAAkB,CAAgC;IAC1D,OAAO,CAAC,uBAAuB,CAA8C;IAC7E,OAAO,CAAC,mBAAmB,CAA6C;IACxE,OAAO,CAAC,WAAW,CAAsB;IACzC,OAAO,CAAC,UAAU,CAA8C;IAChE,OAAO,CAAC,eAAe,CAAqC;IAC5D,OAAO,CAAC,eAAe,CAA+B;IACtD,OAAO,CAAC,aAAa,CAA6B;IAGlD,OAAO,CAAC,sBAAsB,CAAgB;IAG9C,OAAO,CAAC,cAAc,CAAiB;IACvC,OAAO,CAAC,gBAAgB,CAAiB;IACzC,OAAO,CAAC,gBAAgB,CAAiB;IACzC,OAAO,CAAC,iBAAiB,CAAiB;IAC1C,OAAO,CAAC,gBAAgB,CAAe;IACvC,OAAO,CAAC,cAAc,CAAyC;IAC/D,OAAO,CAAC,kBAAkB,CAAwB;gBAE5B,GAAG,EAAE,kBAAkB;IAEvC,IAAI;YAcI,cAAc;IA8I5B;;;;;OAKG;IACH,OAAO,CAAC,0BAA0B;IAmDlC;;;;;;;OAOG;YACW,cAAc;IAqCtB,KAAK;YAuBG,qBAAqB;IA6FnC;;;;OAIG;IACH,OAAO,CAAC,kBAAkB;YA2DZ,eAAe;IA8G7B;;;;;;OAMG;YACW,cAAc;IA0L5B,2DAA2D;IAC3D,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IA2ER,QAAQ;CAwCf"}

package/dist/src/provider/server_stats_provider.js

@@ -1,7 +1,5 @@
 import { readFileSync } from 'node:fs';
 import { getLogStreamService } from '../collectors/log_collector.js';
-import { DashboardStore } from '../dashboard/dashboard_store.js';
-import { DataAccess } from '../data/data_access.js';
 import { DebugStore } from '../debug/debug_store.js';
 import { StatsEngine } from '../engine/stats_engine.js';
 import { LogStreamService } from '../log_stream/log_stream_service.js';
@@ -23,6 +21,8 @@ export default class ServerStatsProvider {
     statsController = null;
     debugController = null;
     apiController = null;
+    // Dashboard dependency check (set in boot, read in ready)
+    dashboardDepsAvailable = true;
     // Diagnostics tracking
     pinoHookActive = false;
     edgePluginActive = false;
@@ -35,9 +35,24 @@ export default class ServerStatsProvider {
         this.app = app;
     }
     async boot() {
+        try {
+            await this.initializeBoot();
+        }
+        catch (err) {
+            log.warn(`boot failed: ${err?.message ?? err}\n` +
+                `  ${dim('The server will continue without server-stats.')}`);
+            if (err?.stack) {
+                console.error(err.stack);
+            }
+        }
+    }
+    async initializeBoot() {
         const config = this.app.config.get('server_stats');
-        if (!config)
+        if (!config) {
+            log.warn('no config found — is config/server_stats.ts set up?');
             return;
+        }
+        log.info('booting...');
         // Wire up the per-request shouldShow callback
         if (config.shouldShow) {
             setShouldShow(config.shouldShow);
@@ -58,7 +73,36 @@ export default class ServerStatsProvider {
             const debugEndpoint = toolbarConfig?.enabled
                 ? (toolbarConfig.debugEndpoint ?? '/admin/api/debug')
                 : undefined;
-            const dashboardPath = toolbarConfig?.enabled && toolbarConfig.dashboard
+            // Check dashboard dependencies before registering dashboard routes.
+            // Must use appImport — bare import() resolves to this package's
+            // devDeps when symlinked, not the app's actual dependencies.
+            if (toolbarConfig?.enabled && toolbarConfig.dashboard) {
+                const { appImport } = await import('../utils/app_import.js');
+                const missing = [];
+                try {
+                    await appImport('knex');
+                }
+                catch {
+                    missing.push('knex');
+                }
+                try {
+                    await appImport('better-sqlite3');
+                }
+                catch {
+                    missing.push('better-sqlite3');
+                }
+                if (missing.length > 0) {
+                    this.dashboardDepsAvailable = false;
+                    log.block(`Dashboard requires ${missing.join(' and ')}. Install with:`, [
+                        '',
+                        bold(`npm install ${missing.join(' ')}`),
+                        '',
+                        dim('Dashboard routes have been skipped for now.'),
+                        dim('Everything else (stats bar, debug panel) works without it.'),
+                    ]);
+                }
+            }
+            const dashboardPath = toolbarConfig?.enabled && toolbarConfig.dashboard && this.dashboardDepsAvailable
                 ? (toolbarConfig.dashboardPath ?? '/__stats')
                 : undefined;
             // ── Register all routes via the unified registrar ──────────
@@ -85,7 +129,7 @@ export default class ServerStatsProvider {
             }
             // Log registered routes
             if (registeredPaths.length > 0) {
-                log.list('routes registered:', registeredPaths);
+                log.list('routes auto-registered (no manual setup needed):', registeredPaths);
                 // Only warn about global auth middleware if:
                 // 1. shouldShow is NOT configured (user hasn't set up access control)
                 // 2. There IS auth middleware in server.use() or router.use()
@@ -118,7 +162,11 @@ export default class ServerStatsProvider {
         if (!this.app.usingEdgeJS)
             return;
         try {
-            const edge = await import('edge.js');
+            // Must use appImport for edge.js — when this package is symlinked,
+            // bare import('edge.js') resolves to the package's devDep copy,
+            // which is a different singleton than the app's Edge instance.
+            const { appImport } = await import('../utils/app_import.js');
+            const edge = await appImport('edge.js');
             const { edgePluginServerStats } = await import('../edge/plugin.js');
             edge.default.use(edgePluginServerStats(config));
             this.edgePluginActive = true;
@@ -228,6 +276,21 @@ export default class ServerStatsProvider {
             return;
         if (this.app.inTest && config.skipInTest !== false)
             return;
+        // Defer the entire initialization to setImmediate so ready() returns
+        // immediately. AdonisJS waits for all provider ready() hooks before
+        // processing HTTP requests — blocking here would hang the server.
+        // Routes use lazy controller getters that return 503 until init completes.
+        setImmediate(() => {
+            this.initializeServerStats(config).catch((err) => {
+                log.warn(`failed to initialize: ${err?.message ?? err}\n` +
+                    `  ${dim('The server will continue without server-stats.')}`);
+                if (err?.stack) {
+                    console.error(err.stack);
+                }
+            });
+        });
+    }
+    async initializeServerStats(config) {
         this.resolvedConfig = config;
         let collectors;
         if (!config.collectors || config.collectors === 'auto') {
@@ -251,21 +314,27 @@ export default class ServerStatsProvider {
         // Dev toolbar setup
         const toolbarConfig = config.devToolbar;
         if (toolbarConfig?.enabled && !this.app.inProduction) {
-            await this.setupDevToolbar({
-                enabled: true,
-                maxQueries: toolbarConfig.maxQueries ?? 500,
-                maxEvents: toolbarConfig.maxEvents ?? 200,
-                maxEmails: toolbarConfig.maxEmails ?? 100,
-                slowQueryThresholdMs: toolbarConfig.slowQueryThresholdMs ?? 100,
-                persistDebugData: toolbarConfig.persistDebugData ?? false,
-                tracing: toolbarConfig.tracing ?? false,
-                maxTraces: toolbarConfig.maxTraces ?? 200,
-                dashboard: toolbarConfig.dashboard ?? false,
-                dashboardPath: toolbarConfig.dashboardPath ?? '/__stats',
-                retentionDays: toolbarConfig.retentionDays ?? 7,
-                dbPath: toolbarConfig.dbPath ?? '.adonisjs/server-stats/dashboard.sqlite3',
-                debugEndpoint: toolbarConfig.debugEndpoint ?? '/admin/api/debug',
-            });
+            try {
+                await this.setupDevToolbar({
+                    enabled: true,
+                    maxQueries: toolbarConfig.maxQueries ?? 500,
+                    maxEvents: toolbarConfig.maxEvents ?? 200,
+                    maxEmails: toolbarConfig.maxEmails ?? 100,
+                    slowQueryThresholdMs: toolbarConfig.slowQueryThresholdMs ?? 100,
+                    persistDebugData: toolbarConfig.persistDebugData ?? false,
+                    tracing: toolbarConfig.tracing ?? false,
+                    maxTraces: toolbarConfig.maxTraces ?? 200,
+                    dashboard: toolbarConfig.dashboard ?? false,
+                    dashboardPath: toolbarConfig.dashboardPath ?? '/__stats',
+                    retentionDays: toolbarConfig.retentionDays ?? 7,
+                    dbPath: toolbarConfig.dbPath ?? '.adonisjs/server-stats/dashboard.sqlite3',
+                    debugEndpoint: toolbarConfig.debugEndpoint ?? '/admin/api/debug',
+                });
+            }
+            catch (err) {
+                log.warn(`dev toolbar setup failed: ${err?.message ?? err}\n` +
+                    `  ${dim('Stats bar will still work, but debug panel may be unavailable.')}`);
+            }
             // Exclude the stats endpoint and user-specified prefixes from tracing
             // so the debug panel's own polling doesn't flood the timeline
             const debugEndpoint = toolbarConfig.debugEndpoint ?? '/admin/api/debug';
@@ -277,41 +346,58 @@ export default class ServerStatsProvider {
             if (prefixes.length > 0) {
                 setExcludedPrefixes(prefixes);
             }
-            // Create the unified ApiController now that both stores are available
+            // Create the unified ApiController now that debug store is available.
+            // Dashboard store is passed as a getter so it picks up the reference
+            // once setupDashboard() completes asynchronously.
             if (this.debugStore) {
                 const logPath = this.app.makePath('logs', 'adonisjs.log');
-                const dataAccess = new DataAccess(this.debugStore, this.dashboardStore, logPath);
+                const { DataAccess: DataAccessClass } = await import('../data/data_access.js');
+                const dataAccess = new DataAccessClass(this.debugStore, () => this.dashboardStore, logPath);
                 const { ApiController: ApiControllerClass } = await import('../controller/api_controller.js');
                 this.apiController = new ApiControllerClass(dataAccess);
             }
         }
+        // ── Stats collection interval + transmit (lightweight, set up inline) ──
+        this.setupStatsInterval(config);
+        log.info('ready');
+    }
+    /**
+     * Set up the stats collection interval, transmit broadcasting,
+     * and Prometheus integration. Extracted from initializeServerStats
+     * so the ready log fires promptly.
+     */
+    setupStatsInterval(config) {
         let transmit = null;
-        if (config.transport === 'transmit') {
-            try {
-                transmit = await this.app.container.make('transmit');
-                if (transmit) {
-                    this.transmitAvailable = true;
-                    if (config.channelName) {
-                        this.transmitChannels.push(config.channelName);
+        let prometheusCollector = null;
+        // Resolve transmit + prometheus asynchronously but don't block ready()
+        const resolveIntegrations = async () => {
+            if (config.transport === 'transmit') {
+                try {
+                    transmit = await this.app.container.make('transmit');
+                    if (transmit) {
+                        this.transmitAvailable = true;
+                        if (config.channelName) {
+                            this.transmitChannels.push(config.channelName);
+                        }
                     }
                 }
+                catch {
+                    log.info('transport is "transmit" but @adonisjs/transmit is not installed — falling back to polling');
+                }
+            }
+            try {
+                const mod = await import('../prometheus/prometheus_collector.js');
+                prometheusCollector = mod.ServerStatsCollector.instance;
             }
             catch {
-                log.info('transport is "transmit" but @adonisjs/transmit is not installed — falling back to polling');
+                // Prometheus not installed — skip (optional dependency)
             }
-        }
-        let prometheusCollector = null;
-        try {
-            const mod = await import('../prometheus/prometheus_collector.js');
-            prometheusCollector = mod.ServerStatsCollector.instance;
-        }
-        catch {
-            // Prometheus not installed — skip (optional dependency)
-        }
-        if (prometheusCollector) {
-            this.prometheusActive = true;
-            log.info('Prometheus integration active');
-        }
+            if (prometheusCollector) {
+                this.prometheusActive = true;
+                log.info('Prometheus integration active');
+            }
+        };
+        resolveIntegrations().catch(() => { });
         this.intervalId = setInterval(async () => {
             try {
                 const stats = await this.engine.collect();
@@ -365,6 +451,7 @@ export default class ServerStatsProvider {
             getEngine: () => this.engine,
             getDashboardStore: () => this.dashboardStore,
             getProviderDiagnostics: () => this.getDiagnostics(),
+            getApp: () => this.app,
         });
         // Wire trace collector into the request tracking middleware
         if (this.debugStore.traces) {
@@ -415,9 +502,17 @@ export default class ServerStatsProvider {
                 }, 200);
             });
         }
-        // Full-page dashboard setup (routes already registered in boot)
-        if (toolbarConfig.dashboard) {
-            await this.setupDashboard(toolbarConfig, emitter);
+        // Full-page dashboard setup — deferred with setImmediate so it runs
+        // AFTER the current event-loop cycle completes. This guarantees
+        // ready() returns and AdonisJS can process HTTP requests while the
+        // SQLite store initializes in the background.
+        if (toolbarConfig.dashboard && this.dashboardDepsAvailable) {
+            setImmediate(() => {
+                this.setupDashboard(toolbarConfig, emitter).catch((err) => {
+                    log.warn(`dashboard setup failed: ${err?.message ?? err}\n` +
+                        `  ${dim('Everything else continues to work.')}`);
+                });
+            });
         }
     }
     /**
@@ -428,34 +523,76 @@ export default class ServerStatsProvider {
      * This method creates the controller so those routes become functional.
      */
     async setupDashboard(toolbarConfig, emitter) {
-        // Create and start the DashboardStore
-        this.dashboardStore = new DashboardStore(toolbarConfig);
+        log.info('dashboard: initializing SQLite store...');
+        // Dynamically import DashboardStore so knex/better-sqlite3 are truly optional
+        const { DashboardStore: DashboardStoreClass } = await import('../dashboard/dashboard_store.js');
+        this.dashboardStore = new DashboardStoreClass(toolbarConfig);
         const appRoot = this.app.makePath('');
         try {
-            await this.dashboardStore.start(null, emitter, appRoot);
+            // Timeout safety net: if SQLite init hangs (e.g. wrong native binary
+            // loaded via symlink), abort after 15s instead of freezing forever.
+            const TIMEOUT_MS = 15_000;
+            const startPromise = this.dashboardStore.start(null, emitter, appRoot);
+            const timeoutPromise = new Promise((_, reject) => {
+                setTimeout(() => reject(new Error(`Dashboard SQLite initialization timed out after ${TIMEOUT_MS / 1000}s`)), TIMEOUT_MS);
+            });
+            await Promise.race([startPromise, timeoutPromise]);
+            log.info('dashboard: SQLite store ready');
         }
         catch (err) {
             const msg = err?.message || '';
-            if (msg.includes('better-sqlite3') || msg.includes('Cannot find module')) {
-                log.warn('Dashboard requires better-sqlite3. Install it with:\n' +
-                    '  npm install better-sqlite3\n' +
-                    '  Dashboard has been disabled for this session.');
-                this.dashboardStore = null;
-                return;
+            const code = err?.code || '';
+            const isMissingDep = msg.includes('better-sqlite3') ||
+                msg.includes('knex') ||
+                msg.includes('Cannot find module') ||
+                msg.includes('Cannot find package') ||
+                code === 'ERR_MODULE_NOT_FOUND' ||
+                code === 'MODULE_NOT_FOUND';
+            const isTimeout = msg.includes('timed out');
+            if (isMissingDep) {
+                log.block('Dashboard could not start — missing dependencies. Install with:', [
+                    '',
+                    bold('npm install knex better-sqlite3'),
+                    '',
+                    dim('Dashboard has been disabled for this session.'),
+                    dim('Everything else (stats bar, debug panel) works without it.'),
+                ]);
+            }
+            else if (isTimeout) {
+                log.block('Dashboard initialization timed out', [
+                    dim('SQLite setup took too long — this usually means a wrong native'),
+                    dim('binary was loaded (common with symlinked/file: dependencies).'),
+                    '',
+                    dim('Try running:'),
+                    `  ${bold('npm install knex better-sqlite3')}`,
+                    dim('in your app directory to ensure the correct copies are used.'),
+                    '',
+                    dim('Dashboard has been disabled for this session.'),
+                    dim('Everything else (stats bar, debug panel) works without it.'),
+                ]);
             }
-            throw err;
+            else {
+                log.warn(`Dashboard could not start: ${msg}\n` +
+                    `  ${dim('Dashboard has been disabled for this session.')}`);
+                if (err?.stack) {
+                    console.error(err.stack);
+                }
+            }
+            this.dashboardStore = null;
+            return;
         }
-        // Bind to container
-        ;
+        log.info('dashboard: binding to container...');
         this.app.container.singleton('dashboard.store', () => this.dashboardStore);
         // Set dashboard path in middleware for self-exclusion
         setDashboardPath(toolbarConfig.dashboardPath);
         // Create the controller — this makes the routes registered in boot() functional
+        log.info('dashboard: creating controller...');
         const DashboardControllerClass = (await import('../dashboard/dashboard_controller.js')).default;
         this.dashboardController = new DashboardControllerClass(this.dashboardStore, this.app);
         // ── Log piping ────────────────────────────────────────────────
         // If the log collector is already hooked into Pino (zero-config mode),
         // piggyback on it instead of creating a separate file poller.
+        log.info('dashboard: setting up log piping...');
         const existingLogStream = getLogStreamService();
         if (existingLogStream && !existingLogStream['logPath']) {
             // Stream mode — add a listener for dashboard persistence

package/dist/src/utils/app_import.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Dynamically import a module, resolving from the app root (`process.cwd()`)
+ * instead of from this package's location.
+ *
+ * This is critical when `adonisjs-server-stats` is symlinked into the app
+ * (e.g. via `file:../../adonisjs-server-stats` in package.json). Without
+ * this, Node.js dereferences the symlink and resolves bare specifiers from
+ * the package's *real* directory tree — which may contain devDependency
+ * stubs with different module identity than the app's actual packages.
+ *
+ * Falls back to a normal `import()` when `createRequire` resolution fails
+ * (e.g. when the package is installed normally, not symlinked).
+ */
+export declare function appImport<T = unknown>(specifier: string): Promise<T>;
+/**
+ * Same as {@link appImport} but also returns the resolved file path.
+ * Useful for diagnostic logging.
+ */
+export declare function appImportWithPath<T = unknown>(specifier: string): Promise<{
+    module: T;
+    resolvedPath: string;
+}>;
+//# sourceMappingURL=app_import.d.ts.map

package/dist/src/utils/app_import.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app_import.d.ts","sourceRoot":"","sources":["../../../src/utils/app_import.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AACH,wBAAsB,SAAS,CAAC,CAAC,GAAG,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAS1E;AAED;;;GAGG;AACH,wBAAsB,iBAAiB,CAAC,CAAC,GAAG,OAAO,EACjD,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC;IAAE,MAAM,EAAE,CAAC,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CAAC,CAW9C"}

package/dist/src/utils/app_import.js

@@ -0,0 +1,44 @@
+import { createRequire } from 'node:module';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+/**
+ * Dynamically import a module, resolving from the app root (`process.cwd()`)
+ * instead of from this package's location.
+ *
+ * This is critical when `adonisjs-server-stats` is symlinked into the app
+ * (e.g. via `file:../../adonisjs-server-stats` in package.json). Without
+ * this, Node.js dereferences the symlink and resolves bare specifiers from
+ * the package's *real* directory tree — which may contain devDependency
+ * stubs with different module identity than the app's actual packages.
+ *
+ * Falls back to a normal `import()` when `createRequire` resolution fails
+ * (e.g. when the package is installed normally, not symlinked).
+ */
+export async function appImport(specifier) {
+    try {
+        const appRequire = createRequire(join(process.cwd(), 'package.json'));
+        const resolved = appRequire.resolve(specifier);
+        return await import(pathToFileURL(resolved).href);
+    }
+    catch {
+        // Fallback: normal import (works when not symlinked)
+        return await import(specifier);
+    }
+}
+/**
+ * Same as {@link appImport} but also returns the resolved file path.
+ * Useful for diagnostic logging.
+ */
+export async function appImportWithPath(specifier) {
+    try {
+        const appRequire = createRequire(join(process.cwd(), 'package.json'));
+        const resolved = appRequire.resolve(specifier);
+        const module = await import(pathToFileURL(resolved).href);
+        return { module: module, resolvedPath: resolved };
+    }
+    catch {
+        // Fallback: normal import (works when not symlinked)
+        const module = await import(specifier);
+        return { module: module, resolvedPath: `(bare import: ${specifier})` };
+    }
+}

package/dist/vue/{CacheSection-CkrIB4-j.js → CacheSection-C788Yfai.js}

@@ -1,5 +1,5 @@
 import { defineComponent as E, inject as v, ref as h, computed as C, openBlock as a, createElementBlock as l, createElementVNode as e, toDisplayString as c, createCommentVNode as g, createVNode as F, unref as y, Fragment as N, renderList as A, withModifiers as B, createBlock as U } from "vue";
-import { u as H } from "./index-COgsk_nv.js";
+import { u as H } from "./index-qCQpBftQ.js";
 import { u as M } from "./useResizableTable-BoivAevK.js";
 import { DashboardApi as j, formatCacheSize as q, formatTtl as I } from "adonisjs-server-stats/core";
 import { u as G } from "./useApiClient-BQQ9CF-q.js";

package/dist/vue/{ConfigSection-gulpOiq1.js → ConfigSection-CRzYxqW2.js}

@@ -1,5 +1,5 @@
 import { defineComponent as re, inject as m, ref as w, computed as x, openBlock as i, createElementBlock as r, createElementVNode as n, normalizeClass as a, createCommentVNode as b, Fragment as _, toDisplayString as u, unref as c, renderList as A, withModifiers as I, normalizeStyle as R } from "vue";
-import { u as ue } from "./index-COgsk_nv.js";
+import { u as ue } from "./index-qCQpBftQ.js";
 import { isRedactedValue as d, flattenConfig as z, TAB_ICONS as g, countLeaves as ce, collectTopLevelObjectKeys as pe, copyWithFeedback as de, formatFlatValue as ve } from "adonisjs-server-stats/core";
 const fe = { style: { position: "relative", flex: 1 } }, he = ["value"], ge = ["title", "onClick"], ye = ["viewBox", "innerHTML"], be = ["viewBox", "innerHTML"], $e = ["onClick"], we = { key: 0 }, xe = ["title", "onClick"], ke = ["viewBox", "innerHTML"], Ce = ["viewBox", "innerHTML"], _e = ["onClick"], Se = { key: 0 }, Be = { style: { padding: "4px 16px", fontSize: "10px", color: "var(--ss-muted)" } }, Le = ["onClick"], He = ["title"], Te = ["title"], je = ["title", "onClick"], Me = ["viewBox", "innerHTML"], me = ["viewBox", "innerHTML"], Ae = ["onClick"], Ie = ["title", "onClick"], Ee = ["viewBox", "innerHTML"], Ve = ["viewBox", "innerHTML"], Oe = {
   key: 1,