@forinda/kickjs-devtools 1.3.1 → 1.4.0

package/dist/index.d.ts

@@ -1,110 +1,3 @@
-import { AppAdapter, Ref, ComputedRef, Container, AdapterMiddleware } from '@forinda/kickjs-core';
-
-/** Per-route latency stats */
-interface RouteStats {
-    count: number;
-    totalMs: number;
-    minMs: number;
-    maxMs: number;
-}
-interface DevToolsOptions {
-    /** Base path for debug endpoints (default: '/_debug') */
-    basePath?: string;
-    /** Only enable when this is true (default: process.env.NODE_ENV !== 'production') */
-    enabled?: boolean;
-    /** Include environment variables (sanitized) at /_debug/config (default: false) */
-    exposeConfig?: boolean;
-    /** Env var prefixes to expose (default: ['APP_', 'NODE_ENV']). Others are redacted. */
-    configPrefixes?: string[];
-    /** Callback when error rate exceeds threshold */
-    onErrorRateExceeded?: (rate: number) => void;
-    /** Error rate threshold (default: 0.5 = 50%) */
-    errorRateThreshold?: number;
-    /** Other adapters to discover stats from (e.g., WsAdapter) */
-    adapters?: any[];
-    /**
-     * Secret token to guard DevTools access. When set, all requests must
-     * include this token as `x-devtools-token` header or `?token=` query param.
-     *
-     * Auto-generated on startup if not provided. The token is logged to the console.
-     * Set to `false` to disable the guard entirely (not recommended).
-     *
-     * @example
-     * ```ts
-     * new DevToolsAdapter({ secret: process.env.DEVTOOLS_SECRET })
-     * ```
-     */
-    secret?: string | false;
-}
-/**
- * DevToolsAdapter — Vue-style reactive introspection for KickJS applications.
- *
- * Exposes debug endpoints powered by reactive state (ref, computed, watch):
- * - `GET /_debug/routes`    — all registered routes with middleware
- * - `GET /_debug/container` — DI registry with scopes and instantiation status
- * - `GET /_debug/metrics`   — live request/error counts, error rate, uptime
- * - `GET /_debug/health`    — deep health check with adapter status
- * - `GET /_debug/config`    — sanitized environment variables (opt-in)
- * - `GET /_debug/state`     — full reactive state snapshot
- *
- * @example
- * ```ts
- * import { DevToolsAdapter } from '@forinda/kickjs-devtools'
- *
- * bootstrap({
- *   modules: [UserModule],
- *   adapters: [
- *     new DevToolsAdapter({
- *       enabled: process.env.NODE_ENV !== 'production',
- *       exposeConfig: true,
- *       configPrefixes: ['APP_', 'DATABASE_'],
- *     }),
- *   ],
- * })
- * ```
- */
-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: any, container: Container): void;
-    middleware(): AdapterMiddleware[];
-    onRouteMount(controllerClass: any, mountPath: string): void;
-    afterStart(_server: any, _container: Container): void;
-    shutdown(): void;
-    /** Find the public/devtools directory relative to the built dist or source */
-    private resolvePublicDir;
-}
-
-export { DevToolsAdapter, type DevToolsOptions };
+import 'reflect-metadata';
+export { DevToolsAdapter, type DevToolsOptions } from './adapter';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,kBAAkB,CAAA;AAEzB,OAAO,EAAE,eAAe,EAAE,KAAK,eAAe,EAAE,MAAM,WAAW,CAAA"}

package/dist/index.js

@@ -1 +1,205 @@
-var R=Object.defineProperty;var p=(v,t)=>R(v,"name",{value:t,configurable:!0});import"reflect-metadata";import{Router as y,static as E}from"express";import{dirname as S,join as c}from"path";import{fileURLToPath as D}from"url";import{existsSync as C,readFileSync as M}from"fs";import{randomBytes as x}from"crypto";import{METADATA as m,ref as l,computed as b,reactive as P,watch as A,createLogger as w}from"@forinda/kickjs-core";var h=w("DevTools"),g=class{static{p(this,"DevToolsAdapter")}name="DevToolsAdapter";basePath;enabled;exposeConfig;configPrefixes;errorRateThreshold;secret;requestCount;errorCount;clientErrorCount;startedAt;errorRate;uptimeSeconds;routeLatency;routes=[];container=null;appRef=null;adapterStatuses={};stopErrorWatch=null;peerAdapters=[];constructor(t={}){if(this.basePath=t.basePath??"/_debug",this.enabled=t.enabled??process.env.NODE_ENV!=="production",this.exposeConfig=t.exposeConfig??!1,this.configPrefixes=t.configPrefixes??["APP_","NODE_ENV"],this.errorRateThreshold=t.errorRateThreshold??.5,this.peerAdapters=t.adapters??[],t.secret===!1?this.secret=!1:t.secret?this.secret=t.secret:this.secret=x(16).toString("hex"),this.requestCount=l(0),this.errorCount=l(0),this.clientErrorCount=l(0),this.startedAt=l(Date.now()),this.routeLatency=P({}),this.errorRate=b(()=>this.requestCount.value>0?this.errorCount.value/this.requestCount.value:0),this.uptimeSeconds=b(()=>Math.floor((Date.now()-this.startedAt.value)/1e3)),t.onErrorRateExceeded){let n=t.onErrorRateExceeded,s=this.errorRateThreshold;this.stopErrorWatch=A(this.errorRate,i=>{i>s&&n(i)})}else this.stopErrorWatch=A(this.errorRate,n=>{n>this.errorRateThreshold&&h.warn(`Error rate elevated: ${(n*100).toFixed(1)}%`)})}getPeerAdapters(){let t=this.appRef?.__kickApp;return t&&typeof t.getAdapters=="function"?t.getAdapters():this.peerAdapters}beforeMount(t,n){if(!this.enabled)return;this.appRef=t,this.container=n,this.startedAt.value=Date.now(),this.routes=[],this.adapterStatuses[this.name]="running";let s=y();if(this.secret!==!1){let o=this.secret;s.use((e,r,a)=>{if((e.headers["x-devtools-token"]??e.query?.token)===o||e.path==="/"&&e.method==="GET"&&!e.query?.token||e.path.endsWith(".js")||e.path.endsWith(".css"))return a();r.status(403).json({error:"Forbidden \u2014 invalid or missing devtools token"})})}s.get("/routes",(o,e)=>{e.json({routes:this.routes})}),s.get("/container",(o,e)=>{let r=this.container?.getRegistrations()??[];e.json({registrations:r,count:r.length})}),s.get("/metrics",(o,e)=>{e.json({requests:this.requestCount.value,serverErrors:this.errorCount.value,clientErrors:this.clientErrorCount.value,errorRate:this.errorRate.value,uptimeSeconds:this.uptimeSeconds.value,startedAt:new Date(this.startedAt.value).toISOString(),routeLatency:this.routeLatency})}),s.get("/health",(o,e)=>{let r=this.errorRate.value<this.errorRateThreshold,a=r?"healthy":"degraded";e.status(r?200:503).json({status:a,errorRate:this.errorRate.value,uptime:this.uptimeSeconds.value,adapters:this.adapterStatuses})}),s.get("/state",(o,e)=>{let r=this.getPeerAdapters().find(a=>a.name==="WsAdapter"&&typeof a.getStats=="function");e.json({reactive:{requestCount:this.requestCount.value,errorCount:this.errorCount.value,clientErrorCount:this.clientErrorCount.value,errorRate:this.errorRate.value,uptimeSeconds:this.uptimeSeconds.value,startedAt:new Date(this.startedAt.value).toISOString()},routes:this.routes.length,container:this.container?.getRegistrations().length??0,routeLatency:this.routeLatency,...r?{ws:r.getStats()}:{}})}),s.get("/ws",(o,e)=>{let r=this.getPeerAdapters().find(a=>a.name==="WsAdapter"&&typeof a.getStats=="function");if(!r){e.json({enabled:!1,message:"WsAdapter not found"});return}e.json({enabled:!0,...r.getStats()})}),s.get("/queues",async(o,e)=>{let r=this.getPeerAdapters().find(a=>a.name==="QueueAdapter"&&typeof a.getQueueNames=="function");if(!r){e.json({enabled:!1,message:"QueueAdapter not found"});return}try{let a=r.getQueueNames?.()??[],u=[];for(let d of a){let f=await r.getQueueStats?.(d);u.push({name:d,...f})}e.json({enabled:!0,queues:u})}catch{e.json({enabled:!0,queues:[],error:"Failed to fetch queue stats"})}}),this.exposeConfig&&s.get("/config",(o,e)=>{let r={};for(let[a,u]of Object.entries(process.env)){if(u===void 0)continue;let d=this.configPrefixes.some(f=>a.startsWith(f));r[a]=d?u:"[REDACTED]"}e.json({config:r})});let i=this.resolvePublicDir();if(i){s.use(E(i));let o=M(c(i,"index.html"),"utf-8");s.get("/",(e,r)=>{let a=o.replace("<body",`<body data-base="${this.basePath}"`);r.type("html").send(a)})}else s.get("/",(o,e)=>{e.type("html").send("<h1>DevTools: public directory not found</h1>")});t.use(this.basePath,s),this.secret?(h.info(`DevTools mounted at ${this.basePath} [token: ${this.secret}]`),h.info(`Access: ${this.basePath}?token=${this.secret}`)):h.info(`DevTools mounted at ${this.basePath} [no guard]`)}middleware(){return this.enabled?[{handler:p((t,n,s)=>{let i=Date.now();this.requestCount.value++,n.on("finish",()=>{n.statusCode>=500?this.errorCount.value++:n.statusCode>=400&&this.clientErrorCount.value++;let o=`${t.method} ${t.route?.path??t.path}`,e=Date.now()-i;this.routeLatency[o]||(this.routeLatency[o]={count:0,totalMs:0,minMs:1/0,maxMs:0});let r=this.routeLatency[o];r.count++,r.totalMs+=e,r.minMs=Math.min(r.minMs,e),r.maxMs=Math.max(r.maxMs,e)}),s()},"handler"),phase:"beforeGlobal"}]:[]}onRouteMount(t,n){if(!this.enabled)return;let s=Reflect.getMetadata(m.ROUTES,t)??[],i=Reflect.getMetadata(m.CLASS_MIDDLEWARES,t)??[];for(let o of s){let e=Reflect.getMetadata(m.METHOD_MIDDLEWARES,t.prototype,o.handlerName)??[];this.routes.push({method:o.method.toUpperCase(),path:`${n}${o.path==="/"?"":o.path}`,controller:t.name,handler:o.handlerName,middleware:[...i.map(r=>r.name||"anonymous"),...e.map(r=>r.name||"anonymous")]})}}afterStart(t,n){this.enabled&&h.info(`DevTools ready \u2014 ${this.routes.length} routes tracked, ${this.container?.getRegistrations().length??0} DI bindings`)}shutdown(){this.stopErrorWatch?.(),this.adapterStatuses[this.name]="stopped"}resolvePublicDir(){let t=S(D(import.meta.url)),n=[c(t,"..","public","devtools"),c(t,"..","..","public","devtools")];for(let s of n)if(C(c(s,"index.html")))return s;return null}};export{g as DevToolsAdapter};
+import "reflect-metadata";
+import { Router as v, static as A } from "express";
+import { dirname as b, join as c } from "node:path";
+import { fileURLToPath as R } from "node:url";
+import { existsSync as y, readFileSync as E } from "node:fs";
+import { randomBytes as D } from "node:crypto";
+import { METADATA as f, computed as p, createLogger as S, reactive as C, ref as l, watch as m } from "@forinda/kickjs-core";
+var h = S("DevTools"), j = class {
+  name = "DevToolsAdapter";
+  basePath;
+  enabled;
+  exposeConfig;
+  configPrefixes;
+  errorRateThreshold;
+  secret;
+  requestCount;
+  errorCount;
+  clientErrorCount;
+  startedAt;
+  errorRate;
+  uptimeSeconds;
+  routeLatency;
+  routes = [];
+  container = null;
+  appRef = null;
+  adapterStatuses = {};
+  stopErrorWatch = null;
+  peerAdapters = [];
+  constructor(r = {}) {
+    if (this.basePath = r.basePath ?? "/_debug", this.enabled = r.enabled ?? process.env.NODE_ENV !== "production", this.exposeConfig = r.exposeConfig ?? !1, this.configPrefixes = r.configPrefixes ?? ["APP_", "NODE_ENV"], this.errorRateThreshold = r.errorRateThreshold ?? 0.5, this.peerAdapters = r.adapters ?? [], r.secret === !1 ? this.secret = !1 : r.secret ? this.secret = r.secret : this.secret = D(16).toString("hex"), this.requestCount = l(0), this.errorCount = l(0), this.clientErrorCount = l(0), this.startedAt = l(Date.now()), this.routeLatency = C({}), this.errorRate = p(() => this.requestCount.value > 0 ? this.errorCount.value / this.requestCount.value : 0), this.uptimeSeconds = p(() => Math.floor((Date.now() - this.startedAt.value) / 1e3)), r.onErrorRateExceeded) {
+      const n = r.onErrorRateExceeded, s = this.errorRateThreshold;
+      this.stopErrorWatch = m(this.errorRate, (i) => {
+        i > s && n(i);
+      });
+    } else this.stopErrorWatch = m(this.errorRate, (n) => {
+      n > this.errorRateThreshold && h.warn(`Error rate elevated: ${(n * 100).toFixed(1)}%`);
+    });
+  }
+  getPeerAdapters() {
+    const r = this.appRef?.__kickApp;
+    return r && typeof r.getAdapters == "function" ? r.getAdapters() : this.peerAdapters;
+  }
+  beforeMount(r, n) {
+    if (!this.enabled) return;
+    this.appRef = r, this.container = n, this.startedAt.value = Date.now(), this.routes = [], this.adapterStatuses[this.name] = "running";
+    const s = v();
+    if (this.secret !== !1) {
+      const o = this.secret;
+      s.use((e, t, a) => {
+        if ((e.headers["x-devtools-token"] ?? e.query?.token) === o || e.path === "/" && e.method === "GET" && !e.query?.token || e.path.endsWith(".js") || e.path.endsWith(".css")) return a();
+        t.status(403).json({ error: "Forbidden — invalid or missing devtools token" });
+      });
+    }
+    s.get("/routes", (o, e) => {
+      e.json({ routes: this.routes });
+    }), s.get("/container", (o, e) => {
+      const t = this.container?.getRegistrations() ?? [];
+      e.json({
+        registrations: t,
+        count: t.length
+      });
+    }), s.get("/metrics", (o, e) => {
+      e.json({
+        requests: this.requestCount.value,
+        serverErrors: this.errorCount.value,
+        clientErrors: this.clientErrorCount.value,
+        errorRate: this.errorRate.value,
+        uptimeSeconds: this.uptimeSeconds.value,
+        startedAt: new Date(this.startedAt.value).toISOString(),
+        routeLatency: this.routeLatency
+      });
+    }), s.get("/health", (o, e) => {
+      const t = this.errorRate.value < this.errorRateThreshold, a = t ? "healthy" : "degraded";
+      e.status(t ? 200 : 503).json({
+        status: a,
+        errorRate: this.errorRate.value,
+        uptime: this.uptimeSeconds.value,
+        adapters: this.adapterStatuses
+      });
+    }), s.get("/state", (o, e) => {
+      const t = this.getPeerAdapters().find((a) => a.name === "WsAdapter" && typeof a.getStats == "function");
+      e.json({
+        reactive: {
+          requestCount: this.requestCount.value,
+          errorCount: this.errorCount.value,
+          clientErrorCount: this.clientErrorCount.value,
+          errorRate: this.errorRate.value,
+          uptimeSeconds: this.uptimeSeconds.value,
+          startedAt: new Date(this.startedAt.value).toISOString()
+        },
+        routes: this.routes.length,
+        container: this.container?.getRegistrations().length ?? 0,
+        routeLatency: this.routeLatency,
+        ...t ? { ws: t.getStats() } : {}
+      });
+    }), s.get("/ws", (o, e) => {
+      const t = this.getPeerAdapters().find((a) => a.name === "WsAdapter" && typeof a.getStats == "function");
+      if (!t) {
+        e.json({
+          enabled: !1,
+          message: "WsAdapter not found"
+        });
+        return;
+      }
+      e.json({
+        enabled: !0,
+        ...t.getStats()
+      });
+    }), s.get("/queues", async (o, e) => {
+      const t = this.getPeerAdapters().find((a) => a.name === "QueueAdapter" && typeof a.getQueueNames == "function");
+      if (!t) {
+        e.json({
+          enabled: !1,
+          message: "QueueAdapter not found"
+        });
+        return;
+      }
+      try {
+        const a = t.getQueueNames?.() ?? [], u = [];
+        for (const d of a) {
+          const g = await t.getQueueStats?.(d);
+          u.push({
+            name: d,
+            ...g
+          });
+        }
+        e.json({
+          enabled: !0,
+          queues: u
+        });
+      } catch {
+        e.json({
+          enabled: !0,
+          queues: [],
+          error: "Failed to fetch queue stats"
+        });
+      }
+    }), this.exposeConfig && s.get("/config", (o, e) => {
+      const t = {};
+      for (const [a, u] of Object.entries(process.env))
+        u !== void 0 && (t[a] = this.configPrefixes.some((d) => a.startsWith(d)) ? u : "[REDACTED]");
+      e.json({ config: t });
+    });
+    const i = this.resolvePublicDir();
+    if (i) {
+      s.use(A(i));
+      const o = E(c(i, "index.html"), "utf-8");
+      s.get("/", (e, t) => {
+        const a = o.replace("<body", `<body data-base="${this.basePath}"`);
+        t.type("html").send(a);
+      });
+    } else s.get("/", (o, e) => {
+      e.type("html").send("<h1>DevTools: public directory not found</h1>");
+    });
+    r.use(this.basePath, s), this.secret ? (h.info(`DevTools mounted at ${this.basePath} [token: ${this.secret}]`), h.info(`Access: ${this.basePath}?token=${this.secret}`)) : h.info(`DevTools mounted at ${this.basePath} [no guard]`);
+  }
+  middleware() {
+    return this.enabled ? [{
+      handler: (r, n, s) => {
+        const i = Date.now();
+        this.requestCount.value++, n.on("finish", () => {
+          n.statusCode >= 500 ? this.errorCount.value++ : n.statusCode >= 400 && this.clientErrorCount.value++;
+          const o = `${r.method} ${r.route?.path ?? r.path}`, e = Date.now() - i;
+          this.routeLatency[o] || (this.routeLatency[o] = {
+            count: 0,
+            totalMs: 0,
+            minMs: 1 / 0,
+            maxMs: 0
+          });
+          const t = this.routeLatency[o];
+          t.count++, t.totalMs += e, t.minMs = Math.min(t.minMs, e), t.maxMs = Math.max(t.maxMs, e);
+        }), s();
+      },
+      phase: "beforeGlobal"
+    }] : [];
+  }
+  onRouteMount(r, n) {
+    if (!this.enabled) return;
+    const s = Reflect.getMetadata(f.ROUTES, r) ?? [], i = Reflect.getMetadata(f.CLASS_MIDDLEWARES, r) ?? [];
+    for (const o of s) {
+      const e = Reflect.getMetadata(f.METHOD_MIDDLEWARES, r.prototype, o.handlerName) ?? [];
+      this.routes.push({
+        method: o.method.toUpperCase(),
+        path: `${n}${o.path === "/" ? "" : o.path}`,
+        controller: r.name,
+        handler: o.handlerName,
+        middleware: [...i.map((t) => t.name || "anonymous"), ...e.map((t) => t.name || "anonymous")]
+      });
+    }
+  }
+  afterStart(r, n) {
+    this.enabled && h.info(`DevTools ready — ${this.routes.length} routes tracked, ${this.container?.getRegistrations().length ?? 0} DI bindings`);
+  }
+  shutdown() {
+    this.stopErrorWatch?.(), this.adapterStatuses[this.name] = "stopped";
+  }
+  resolvePublicDir() {
+    const r = b(R(import.meta.url)), n = [c(r, "..", "public", "devtools"), c(r, "..", "..", "public", "devtools")];
+    for (const s of n) if (y(c(s, "index.html"))) return s;
+    return null;
+  }
+};
+export {
+  j as DevToolsAdapter
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forinda/kickjs-devtools",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "description": "Development introspection dashboard for KickJS — routes, DI container, metrics, health",
   "keywords": [
     "kickjs",
@@ -35,7 +35,8 @@
     "@forinda/kickjs-mailer",
     "@forinda/kickjs-queue",
     "@forinda/kickjs-multi-tenant",
-    "@forinda/kickjs-notifications"
+    "@forinda/kickjs-notifications",
+    "vite"
   ],
   "type": "module",
   "main": "dist/index.js",
@@ -52,7 +53,7 @@
   ],
   "dependencies": {
     "reflect-metadata": "^0.2.2",
-    "@forinda/kickjs-core": "1.3.1"
+    "@forinda/kickjs-core": "1.4.0"
   },
   "peerDependencies": {
     "express": "^5.1.0"
@@ -61,7 +62,6 @@
     "@types/express": "^5.0.6",
     "@types/node": "^24.5.2",
     "express": "^5.1.0",
-    "tsup": "^8.5.0",
     "typescript": "^5.9.2",
     "vitest": "^3.2.4"
   },
@@ -83,8 +83,9 @@
     "url": "https://github.com/forinda/kick-js/issues"
   },
   "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
+    "build": "vite build && pnpm build:types",
+    "build:types": "tsc -p tsconfig.build.json",
+    "dev": "vite build --watch",
     "test": "vitest run --passWithNoTests",
     "typecheck": "tsc --noEmit",
     "clean": "rm -rf dist .turbo"