@forinda/kickjs-devtools 3.2.0 → 4.1.0

package/README.md

@@ -1,60 +1,37 @@
 # @forinda/kickjs-devtools
 
-Development introspection dashboard for KickJS — routes, DI container, metrics, and health.
+Dev introspection dashboard — routes, DI container state, request metrics, p50/p95/p99 latency, error-rate alerts, dependency graph, SSE stream. Mounted under `/_debug` and gated by an auto-generated token.
 
 ## Install
 
 ```bash
-# Using the KickJS CLI (recommended — installs as dev dependency)
 kick add devtools
-
-# Manual install
-pnpm add -D @forinda/kickjs-devtools
 ```
 
-## Features
-
-- `DevToolsAdapter` — lifecycle adapter that mounts debug endpoints
-- Route inspection, DI container state, request metrics, health checks
-- Config exposure with prefix-based redaction
-- Error rate threshold alerts
-- Reactive state snapshot via `/_debug/state`
-
-## Debug Endpoints
-
-| Endpoint | Description |
-|----------|-------------|
-| `GET /_debug/routes` | All registered routes with middleware |
-| `GET /_debug/container` | DI container state |
-| `GET /_debug/metrics` | Request counts, error rate, latency |
-| `GET /_debug/health` | Health status (200 or 503) |
-| `GET /_debug/state` | Full reactive state snapshot |
-| `GET /_debug/config` | Sanitized environment variables |
-
 ## Quick Example
 
-```typescript
+```ts
+import { bootstrap, getEnv } from '@forinda/kickjs'
 import { DevToolsAdapter } from '@forinda/kickjs-devtools'
+import { modules } from './modules'
 
-bootstrap({
+export const app = await bootstrap({
   modules,
   adapters: [
-    new DevToolsAdapter({
-      enabled: true,
+    DevToolsAdapter({
+      secret: getEnv('NODE_ENV') === 'production' ? undefined : false,
       exposeConfig: true,
       configPrefixes: ['APP_', 'NODE_ENV', 'PORT'],
-      errorRateThreshold: 0.3,
-      onErrorRateExceeded: (rate) => {
-        console.warn(`Error rate: ${(rate * 100).toFixed(1)}%`)
-      },
     }),
   ],
 })
 ```
 
+Endpoints (token-gated unless `secret: false`): `/_debug/{routes,container,metrics,health,state,config,graph,stream,ws,queues}` — plus a Vue + Tailwind dashboard at `/_debug/`.
+
 ## Documentation
 
-[Full documentation](https://forinda.github.io/kick-js/guide/devtools)
+[forinda.github.io/kick-js/guide/devtools](https://forinda.github.io/kick-js/guide/devtools)
 
 ## License
 

package/dist/index.d.mts

@@ -1,5 +1,7 @@
 
-import { AdapterContext, AdapterMiddleware, AppAdapter, ComputedRef, Ref } from "@forinda/kickjs";
+import * as _$_forinda_kickjs0 from "@forinda/kickjs";
+import { ComputedRef, Ref } from "@forinda/kickjs";
+import { MemoryAnalyzer, RuntimeSampler } from "@forinda/kickjs-devtools-kit";
 
 //#region src/adapter.d.ts
 /** Per-route latency stats with percentile tracking */
@@ -35,10 +37,57 @@ interface DevToolsOptions {
    *
    * @example
    * ```ts
-   * new DevToolsAdapter({ secret: process.env.DEVTOOLS_SECRET })
+   * DevToolsAdapter({ secret: getEnv('DEVTOOLS_SECRET') })
    * ```
    */
   secret?: string | false;
+  /**
+   * Tuning for the runtime sampler that powers `/_debug/runtime` and
+   * the upcoming Memory tab (architecture.md §23). Defaults to
+   * 1-second polling with a 60-sample (~1 minute) ring buffer.
+   *
+   * Set `runtime.enabled = false` to skip starting the sampler — the
+   * `/_debug/runtime` endpoint then returns 404 instead of an empty
+   * snapshot, signalling deliberate opt-out rather than a startup race.
+   */
+  runtime?: {
+    /** Whether to start the runtime sampler at all. Default: true. */enabled?: boolean; /** Polling interval in milliseconds. Default: 1000. */
+    intervalMs?: number; /** Ring-buffer size — number of past samples retained. Default: 60. */
+    bufferSize?: number;
+  };
+}
+/**
+ * Public reactive surface exposed by a DevToolsAdapter instance —
+ * counters, computed metrics, and the route latency map. Tests and
+ * peer adapters consume these directly to drive their own behavior.
+ */
+interface DevToolsAdapterExtensions {
+  /** Total requests received. */
+  readonly requestCount: Ref<number>;
+  /** Total responses with status >= 500. */
+  readonly errorCount: Ref<number>;
+  /** Total responses with status >= 400 and < 500. */
+  readonly clientErrorCount: Ref<number>;
+  /** Server start time. */
+  readonly startedAt: Ref<number>;
+  /** Computed error rate (server errors / total requests). */
+  readonly errorRate: ComputedRef<number>;
+  /** Computed uptime in seconds. */
+  readonly uptimeSeconds: ComputedRef<number>;
+  /** Per-route latency tracking. */
+  readonly routeLatency: Record<string, RouteStats>;
+  /**
+   * Tier-1 runtime sampler from `@forinda/kickjs-devtools-kit`. `null`
+   * when `runtime.enabled` is `false`. Tests can `latest()` and
+   * `history()` directly without going through the HTTP endpoint.
+   */
+  readonly runtimeSampler: RuntimeSampler | null;
+  /**
+   * Memory analyzer fed by the runtime sampler. `null` when the
+   * sampler is disabled. Use `analyzer.health(sampler.history())` to
+   * compose a composite memory-health snapshot.
+   */
+  readonly memoryAnalyzer: MemoryAnalyzer | null;
 }
 /**
  * DevToolsAdapter — Vue-style reactive introspection for KickJS applications.
@@ -58,7 +107,7 @@ interface DevToolsOptions {
  * bootstrap({
  *   modules: [UserModule],
  *   adapters: [
- *     new DevToolsAdapter({
+ *     DevToolsAdapter({
  *       enabled: process.env.NODE_ENV !== 'production',
  *       exposeConfig: true,
  *       configPrefixes: ['APP_', 'DATABASE_'],
@@ -67,52 +116,7 @@ interface DevToolsOptions {
  * })
  * ```
  */
-declare class DevToolsAdapter implements AppAdapter {
-  readonly name = "DevToolsAdapter";
-  private basePath;
-  private enabled;
-  private exposeConfig;
-  private configPrefixes;
-  private errorRateThreshold;
-  private secret;
-  /** Total requests received */
-  readonly requestCount: Ref<number>;
-  /** Total responses with status >= 500 */
-  readonly errorCount: Ref<number>;
-  /** Total responses with status >= 400 and < 500 */
-  readonly clientErrorCount: Ref<number>;
-  /** Server start time */
-  readonly startedAt: Ref<number>;
-  /** Computed error rate (server errors / total requests) */
-  readonly errorRate: ComputedRef<number>;
-  /** Computed uptime in seconds */
-  readonly uptimeSeconds: ComputedRef<number>;
-  /** Per-route latency tracking */
-  readonly routeLatency: Record<string, RouteStats>;
-  private routes;
-  private container;
-  private appRef;
-  private adapterStatuses;
-  private stopErrorWatch;
-  private peerAdapters;
-  constructor(options?: DevToolsOptions);
-  /**
-   * Resolve peer adapters at request time. Prefers live adapters from the
-   * Application registry (survives HMR rebuild) and falls back to the
-   * constructor-provided refs.
-   */
-  private getPeerAdapters;
-  beforeMount({
-    app,
-    container
-  }: AdapterContext): void;
-  middleware(): AdapterMiddleware[];
-  onRouteMount(controllerClass: any, mountPath: string): void;
-  afterStart({}: AdapterContext): void;
-  shutdown(): void;
-  /** Find the public/devtools directory relative to the built dist or source */
-  private resolvePublicDir;
-}
+declare const DevToolsAdapter: _$_forinda_kickjs0.AdapterFactory<DevToolsOptions, DevToolsAdapterExtensions>;
 //#endregion
 export { DevToolsAdapter, type DevToolsOptions };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/adapter.ts"],"mappings":";;;;;UAmCU,UAAA;EACR,KAAA;EACA,OAAA;EACA,KAAA;EACA,KAAA;EAJkB;EAMlB,OAAA;AAAA;AAAA,UAsBe,eAAA;EAxBf;EA0BA,QAAA;EAxBO;EA0BP,OAAA;EAJe;EAMf,YAAA;;EAEA,cAAA;EANA;EAQA,mBAAA,IAAuB,IAAA;EAJvB;EAMA,kBAAA;EAFA;EAIA,QAAA;EAFA;;;;;AA8CF;;;;;;;EA9BE,MAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;cA8BW,eAAA,YAA2B,UAAA;EAAA,SAC7B,IAAA;EAAA,QAED,QAAA;EAAA,QACA,OAAA;EAAA,QACA,YAAA;EAAA,QACA,cAAA;EAAA,QACA,kBAAA;EAAA,QACA,MAAA;EAoBA;EAAA,SAhBC,YAAA,EAAc,GAAA;EAkBf;EAAA,SAhBC,UAAA,EAAY,GAAA;EAkBb;EAAA,SAhBC,gBAAA,EAAkB,GAAA;EAkBN;EAAA,SAhBZ,SAAA,EAAW,GAAA;EAwEZ;EAAA,SAtEC,SAAA,EAAW,WAAA;EA8EN;EAAA,SA5EL,aAAA,EAAe,WAAA;EA4EL;EAAA,SA1EV,YAAA,EAAc,MAAA,SAAe,UAAA;EAAA,QAG9B,MAAA;EAAA,QACA,SAAA;EAAA,QACA,MAAA;EAAA,QACA,eAAA;EAAA,QACA,cAAA;EAAA,QACA,YAAA;cAEI,OAAA,GAAS,eAAA;EAuXN;;;;;EAAA,QA/TP,eAAA;EAQR,WAAA,CAAA;IAAc,GAAA;IAAK;EAAA,GAAa,cAAA;EA6OhC,UAAA,CAAA,GAAc,iBAAA;EA0Cd,YAAA,CAAa,eAAA,OAAsB,SAAA;EAgCnC,UAAA,CAAA,IAAe,cAAA;EAQf,QAAA,CAAA;;UAMQ,gBAAA;AAAA"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/adapter.ts"],"mappings":";;;;;;;UA4CU,UAAA;EACR,KAAA;EACA,OAAA;EACA,KAAA;EACA,KAAA;;EAEA,OAAA;AAAA;AAAA,UA4De,eAAA;EA/Df;EAiEA,QAAA;EA9DA;EAgEA,OAAA;EAhEO;EAkEP,YAAA;EAN8B;EAQ9B,cAAA;EAR8B;EAU9B,mBAAA,IAAuB,IAAA;EANvB;EAQA,kBAAA;EAJA;EAMA,QAAA;EAJuB;;;;;;;;;;AA4CzB;;EA1BE,MAAA;EA4BuB;;;;;;;;;EAjBvB,OAAA;IAyCuC,kEAvCrC,OAAA,YAeO;IAbP,UAAA,WAeO;IAbP,UAAA;EAAA;AAAA;;;;;;UASa,yBAAA;EAcN;EAAA,SAZA,YAAA,EAAc,GAAA;EAYe;EAAA,SAV7B,UAAA,EAAY,GAAA;EAgBI;EAAA,SAdhB,gBAAA,EAAkB,GAAA;EAoBF;EAAA,SAlBhB,SAAA,EAAW,GAAA;EAkBmB;EAAA,SAhB9B,SAAA,EAAW,WAAA;EAguBpB;EAAA,SA9tBS,aAAA,EAAe,WAAA;EA4CE;EAAA,SA1CjB,YAAA,EAAc,MAAA,SAAe,UAAA;EA0CZ;;;;;EAAA,SApCjB,cAAA,EAAgB,cAAA;EAoCC;;;;;EAAA,SA9BjB,cAAA,EAAgB,cAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;cA8Bd,eAAA,EAAe,kBAAA,CAAA,cAAA,CAAA,eAAA,EAAA,yBAAA"}