@singhak/nodeui-core 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,582 @@
+import { Readable } from 'node:stream';
+import { ServerResponse, IncomingMessage } from 'node:http';
+
+/**
+ * Shared typed contract for the NodeUI developer console.
+ *
+ * The core engine, both adapters, and the browser console all speak this
+ * contract. Every provider returns a {@link ProviderResult}; every REST
+ * endpoint returns an {@link ApiEnvelope} which is the same shape.
+ */
+type PanelId = 'health' | 'memory' | 'cpu' | 'event-loop' | 'heap-snapshot' | 'startup' | 'requests' | 'env' | 'routes' | 'logs' | 'metrics';
+/** Resolved, validated console configuration. */
+interface NodeUIConfig {
+    /** URL path prefix where the console and its API are served. Default `/nodeui`. */
+    path: string;
+    /** Interface the console considers its own. Default `127.0.0.1`. */
+    host: string;
+    /** Informational port of the host application. */
+    port: number;
+    /** Ring buffer capacity for the HTTP request log. Default 500. */
+    requestLogSize: number;
+    /** Ring buffer capacity for the log viewer. Default 500. */
+    logSize: number;
+    /** Sampling/polling interval in ms. Default 2000. */
+    pollIntervalMs: number;
+    /** Whether the console is active (see {@link resolveActivation}). */
+    enabled: boolean;
+    /** Human-readable explanation of the activation decision. */
+    activationReason: string;
+    /** Whether secret masking is applied to panel output. Default true. */
+    maskSecrets: boolean;
+    /** Idle time after which background samplers stop. Default 60000. */
+    inactivityTimeoutMs: number;
+    /** TTL for mutation confirmation nonces. Default 60000. */
+    confirmTtlMs: number;
+    /** Directory where heap snapshot files are written. */
+    heapSnapshotDir: string;
+}
+/** Context handed to every provider call. */
+interface ProviderContext {
+    config: NodeUIConfig;
+    /** Environment snapshot (injectable for tests; defaults to `process.env`). */
+    env: Record<string, string | undefined>;
+    /** Shared scratch pad providers can read/write. */
+    store: Record<string, unknown>;
+    /** Query parameters of the current API request (e.g. `?level=`). */
+    query?: Record<string, string>;
+}
+interface ProviderError {
+    /** Stable machine-readable code, e.g. `confirmation-required`. */
+    code: string;
+    /** Human-readable message. */
+    message: string;
+}
+/**
+ * Typed provider result. Success carries `data`; failure carries a
+ * `ProviderError`. Providers never throw to the caller.
+ */
+type ProviderResult<T> = {
+    ok: true;
+    data: T;
+} | {
+    ok: false;
+    error: ProviderError;
+};
+/** The envelope returned by every REST endpoint. */
+type ApiEnvelope<T> = ProviderResult<T>;
+/**
+ * One provider per panel. Providers that sample in the background implement
+ * `start`/`stop`; the server starts them lazily on first view and stops them
+ * after a period of inactivity.
+ */
+interface NodeUIProvider<T = unknown> {
+    readonly id: PanelId;
+    start?(ctx: ProviderContext): void;
+    stop?(ctx: ProviderContext): void;
+    get(ctx: ProviderContext): ProviderResult<T> | Promise<ProviderResult<T>>;
+}
+/** Event-loop lag sample. */
+interface EventLoopSample {
+    currentMs: number;
+    maxMs: number;
+    avgMs: number;
+    count: number;
+    sampleAtMs: number;
+}
+interface MemoryData {
+    heapUsed: number;
+    heapTotal: number;
+    rss: number;
+    external: number;
+    totalMem: number;
+    freeMem: number;
+    sampleAtMs: number;
+}
+interface CpuData {
+    userPercent: number;
+    systemPercent: number;
+    totalPercent: number;
+    sampleAtMs: number;
+}
+interface HealthData {
+    status: 'ok' | 'degraded' | 'critical' | 'unknown';
+    statusReason: string;
+    uptimeSeconds: number;
+    pid: number;
+    nodeVersion: string;
+    platform: string;
+    eventLoopLagMs: number | null;
+    memoryUsedPercent: number | null;
+}
+interface StartupMark {
+    name: string;
+    atMs: number;
+    /** Milliseconds since the first recorded mark. */
+    sinceFirstMs: number;
+}
+interface StartupData {
+    startedAtMs: number;
+    marks: StartupMark[];
+}
+interface RequestEntry {
+    id: number;
+    method: string;
+    path: string;
+    status: number;
+    durationMs: number;
+    timestampMs: number;
+    ip: string;
+}
+interface RequestsData {
+    total: number;
+    entries: RequestEntry[];
+}
+interface EnvEntry {
+    key: string;
+    value: string;
+}
+interface EnvData {
+    environment: EnvEntry[];
+    config: EnvEntry[] | null;
+}
+interface RouteEntry {
+    method: string;
+    path: string;
+    handler: string;
+}
+interface RoutesData {
+    routes: RouteEntry[];
+}
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+interface LogEntry {
+    level: LogLevel;
+    message: string;
+    timestamp: number;
+}
+interface LogsData {
+    entries: LogEntry[];
+}
+interface MetricsBucket {
+    ts: number;
+    requests: number;
+    errors: number;
+}
+interface MetricsData {
+    buckets: MetricsBucket[];
+}
+interface HeapSnapshotData {
+    fileName: string;
+    filePath: string;
+    sizeBytes: number;
+    createdAtMs: number;
+}
+interface HeapSnapshotPanelData {
+    supported: boolean;
+    lastSnapshot: HeapSnapshotData | null;
+}
+interface ConfirmIssued {
+    nonce: string;
+    expiresAtMs: number;
+    ttlMs: number;
+}
+interface ConfigData {
+    enabled: boolean;
+    activationReason: string;
+    path: string;
+    host: string;
+    port: number;
+    requestLogSize: number;
+    logSize: number;
+    pollIntervalMs: number;
+    panels: PanelId[];
+    masking: {
+        enabled: boolean;
+        pattern: string;
+    };
+}
+
+/** Replacement value used when masking secret values. */
+declare const SECRET_MASKED = "[REDACTED]";
+/** Default ring buffer capacity for the log viewer. */
+declare const DEFAULT_LOG_SIZE = 500;
+
+/**
+ * Fixed-size ring buffer. When full, pushing drops the oldest item.
+ * Used for the HTTP request log to keep memory bounded.
+ */
+declare class RingBuffer<T> {
+    private buffer;
+    private head;
+    private count;
+    readonly capacity: number;
+    constructor(size: number);
+    push(item: T): void;
+    get length(): number;
+    toArray(): T[];
+    /**
+     * Returns up to `limit` items starting at `offset`, oldest first.
+     */
+    slice(offset?: number, limit?: number): T[];
+}
+
+/** Keys whose values are redacted in any panel output. */
+declare const SECRET_KEY_PATTERN: RegExp;
+interface ActivationDecision {
+    active: boolean;
+    reason: string;
+}
+/**
+ * Safety-gate activation. The console is active when `NODEUI_ENABLED=true`
+ * or when `NODE_ENV` is not `production`. `NODEUI_ENABLED=false` explicitly
+ * disables it everywhere (including development). Otherwise it fails closed.
+ */
+declare function resolveActivation(env: Record<string, string | undefined>): ActivationDecision;
+/** True when the socket address is a loopback address. */
+declare function isLoopbackAddress(address: string | undefined): boolean;
+/**
+ * Deep-clone a value, replacing any value under a key matching the secret
+ * pattern with `[REDACTED]`. The input is not mutated.
+ */
+declare function maskSecrets<T>(value: T, pattern?: RegExp): T;
+
+/**
+ * Single-use, expiring confirmation nonces. Mutating actions (such as heap
+ * snapshots) require a nonce issued here, presented via the
+ * `x-nodeui-confirm` header, which is consumed exactly once.
+ */
+declare class ConfirmationStore {
+    private readonly ttlMs;
+    private nonces;
+    constructor(ttlMs: number);
+    issue(): ConfirmIssued;
+    /** Consumes `nonce` and returns true only if it was valid and unexpired. */
+    consume(nonce: string): boolean;
+    /** Number of currently valid nonces (after pruning). */
+    size(): number;
+    /** Removes expired nonces. */
+    prune(): void;
+}
+
+/** Ordered registry of the standard panel providers. */
+declare class ProviderRegistry {
+    private providers;
+    register(provider: NodeUIProvider): void;
+    get(id: PanelId): NodeUIProvider | undefined;
+    ids(): PanelId[];
+    all(): NodeUIProvider[];
+}
+
+interface StaticAsset {
+    content: Readable;
+    contentType: string;
+    length: number;
+}
+/**
+ * Resolves a URL path to a file inside `rootDir`, serving `index.html` for
+ * directories and falling back to `index.html` for unknown paths (SPA).
+ * Returns null when the path would escape `rootDir`.
+ */
+declare function resolveStaticAsset(rootDir: string, urlPath: string): StaticAsset | null;
+
+interface SamplerOptions<T> {
+    intervalMs: number;
+    collect: () => T;
+    onSample: (sample: T) => void;
+}
+/**
+ * Wraps a tracked `setInterval`. Idempotent `start`, guaranteed `stop`,
+ * and a `collect` that never throws into the event loop. All timers are
+ * cleared on `stop` — no leaks on hot reload.
+ */
+declare class Sampler<T> {
+    private readonly opts;
+    private timer;
+    constructor(opts: SamplerOptions<T>);
+    start(): void;
+    stop(): void;
+    get isRunning(): boolean;
+}
+
+/** Records ordered bootstrap timing marks. */
+declare class StartupTracker {
+    private startedAtMs;
+    private marks;
+    mark(name: string): void;
+    getData(): StartupData;
+    reset(): void;
+}
+
+/** Samples `process.memoryUsage()` plus OS totals on the poll interval. */
+declare class MemoryProvider implements NodeUIProvider<MemoryData> {
+    readonly id: "memory";
+    private sampler;
+    private latest;
+    private collect;
+    start(ctx: ProviderContext): void;
+    stop(): void;
+    get(): {
+        ok: true;
+        data: MemoryData;
+    };
+}
+
+interface CpuUsageSnapshot {
+    user: number;
+    system: number;
+}
+/**
+ * Injectable clock so CPU delta math is unit-testable. `nowUs` returns the
+ * wall clock in microseconds; `cpuUsage` returns cumulative microseconds of
+ * user/system CPU time since process start (like `process.cpuUsage()`).
+ */
+interface CpuClock {
+    nowUs: () => bigint;
+    cpuUsage: () => CpuUsageSnapshot;
+    /** Test hook: advance to the next scripted step. */
+    tick?: () => void;
+}
+/** Computes CPU usage percent via deltas of `process.cpuUsage()`. */
+declare class CpuProvider implements NodeUIProvider<CpuData> {
+    private readonly clock;
+    readonly id: "cpu";
+    private sampler;
+    private latest;
+    private last;
+    constructor(clock?: CpuClock);
+    /** Runs one sampling step immediately; called by the sampler on each tick. */
+    collect(): CpuData;
+    start(ctx: ProviderContext): void;
+    stop(): void;
+    get(): {
+        ok: true;
+        data: CpuData;
+    };
+}
+
+interface EventLoopClock {
+    /** Current time in nanoseconds. */
+    nowNs: () => bigint;
+}
+/**
+ * Measures event-loop lag from a background timer: each tick reports how far
+ * behind the nominal interval the loop actually was. Keeps a rolling window
+ * of samples so the panel can show current/max/average lag.
+ */
+declare class EventLoopLagProvider implements NodeUIProvider<EventLoopSample> {
+    private readonly clock;
+    readonly id: "event-loop";
+    private sampler;
+    private samples;
+    private latest;
+    private lastFireNs;
+    constructor(clock?: EventLoopClock);
+    /** Runs one measurement tick; called by the sampler on each interval. */
+    collect(intervalMs: number): EventLoopSample;
+    start(ctx: ProviderContext): void;
+    stop(): void;
+    get(): {
+        ok: true;
+        data: EventLoopSample;
+    };
+}
+
+/** Derives process + event-loop health from the latest sampled values. */
+declare class HealthProvider implements NodeUIProvider<HealthData> {
+    readonly id: "health";
+    get(ctx: ProviderContext): {
+        ok: true;
+        data: HealthData;
+    };
+}
+
+/**
+ * Heap snapshots via `v8.writeHeapSnapshot`. The panel is read-only; the
+ * actual file write happens only through `takeSnapshot`, which the server
+ * gates behind a confirmation nonce.
+ */
+declare class HeapSnapshotProvider implements NodeUIProvider<HeapSnapshotPanelData> {
+    readonly id: "heap-snapshot";
+    private lastSnapshot;
+    get(): {
+        ok: true;
+        data: HeapSnapshotPanelData;
+    };
+    takeSnapshot(ctx: ProviderContext): Promise<ProviderResult<HeapSnapshotData>>;
+}
+
+/** Fixed-size ring buffer of recent HTTP requests, recorded via middleware hook. */
+declare class RequestsProvider implements NodeUIProvider<RequestsData> {
+    readonly id: "requests";
+    private buffer;
+    private nextId;
+    constructor(size: number);
+    record(entry: Omit<RequestEntry, 'id'>): void;
+    get length(): number;
+    get(): {
+        ok: true;
+        data: RequestsData;
+    };
+}
+
+/**
+ * Records one-second buckets of request counts and error counts, derived from
+ * the request recorder in the server middleware. Errors are responses with
+ * status >= 500.
+ */
+declare class MetricsProvider implements NodeUIProvider<MetricsData> {
+    readonly id: "metrics";
+    private buckets;
+    private readonly nowMs;
+    constructor(nowMs?: () => number);
+    /** Ticks the current second bucket for one completed request. */
+    record(status: number): void;
+    get(): {
+        ok: true;
+        data: MetricsData;
+    };
+}
+
+/**
+ * Environment and app-config viewer. The environment comes from the process
+ * env snapshot; secret masking is applied later at serialization time.
+ */
+declare class EnvProvider implements NodeUIProvider<EnvData> {
+    readonly id: "env";
+    get(ctx: ProviderContext): {
+        ok: true;
+        data: EnvData;
+    };
+}
+
+/**
+ * Recursively walks an Express-style router stack, extracting concrete
+ * method + path + handler entries. Middleware-only layers are skipped.
+ *
+ * NOTE: This intentionally relies on Express router internals
+ * (`router.stack`, `layer.route`, `layer.handle.stack`), which are stable in
+ * Express 4 and 5 but not part of the public API. If a future Express
+ * release changes the shape, this is the only place that needs updating —
+ * the walk degrades to an empty list rather than throwing.
+ */
+declare function extractRoutes(router: unknown): RouteEntry[];
+/**
+ * Lists the HTTP routes of the host application by introspecting the Express
+ * router captured from `req.app._router` (or `req.app.router` on Express 5)
+ * on the first handled request. Results are cached per router reference so
+ * repeated fetches do not re-walk the stack.
+ */
+declare class RoutesProvider implements NodeUIProvider<RoutesData> {
+    readonly id: "routes";
+    private cache;
+    get(ctx: ProviderContext): {
+        ok: true;
+        data: RoutesData;
+    } | {
+        ok: false;
+        error: {
+            code: string;
+            message: string;
+        };
+    };
+}
+
+/**
+ * Wraps `console.debug/info/log/warn/error` to tee entries to every active
+ * `push` callback. Refcounted: the first install replaces the methods, the
+ * last release restores the originals. Supports concurrent consumers (e.g.
+ * multiple `createNodeUI()` instances) — each registers its own push and is
+ * removed independently. Never throws into the caller.
+ */
+declare function interceptConsole(push: (entry: Omit<LogEntry, 'timestamp'>) => void): () => void;
+/**
+ * Log viewer provider. While active it intercepts `console.*` output and
+ * also accepts entries pushed via {@link addSource}. Filtering happens
+ * server-side via `ctx.query.level` and `ctx.query.query`.
+ */
+declare class LogsProvider implements NodeUIProvider<LogsData> {
+    readonly id: "logs";
+    private buffer;
+    private release;
+    constructor(size?: number);
+    start(): void;
+    stop(): void;
+    /** Pushes an external entry (logger adapter). */
+    addSource(entry: {
+        level: LogLevel;
+        message: string;
+    }): void;
+    get(ctx: ProviderContext): {
+        ok: true;
+        data: LogsData;
+    };
+}
+
+interface SseStream {
+    send(payload: unknown): void;
+    heartbeat(): void;
+    close(): void;
+}
+/**
+ * Minimal Server-Sent Events writer over a raw HTTP response. Events are
+ * emitted as `data: <json>\n\n`; heartbeats as `:ping\n\n`.
+ */
+declare function startSse(res: ServerResponse): SseStream;
+
+interface NodeUIOptions {
+    /** URL path prefix. Default `/nodeui` (or `NODEUI_PATH`). */
+    path?: string;
+    /** Interface the console considers its own. Default `127.0.0.1` (or `NODEUI_HOST`). */
+    host?: string;
+    /** Informational port of the host application. */
+    port?: number;
+    /** Ring buffer capacity for the request log. Default 500. */
+    requestLogSize?: number;
+    /** Ring buffer capacity for the log viewer. Default 500. */
+    logSize?: number;
+    /** App config surfaced in the env panel; may be an object or a getter. */
+    config?: unknown | (() => unknown);
+    /** Sampling/polling interval in ms. Default 2000. */
+    pollIntervalMs?: number;
+    /** Explicit activation override. Defaults to env-based activation. */
+    enabled?: boolean;
+    /** Environment snapshot. Defaults to `process.env`. */
+    env?: Record<string, string | undefined>;
+    /** Whether secret masking applies to panel output. Default true. */
+    maskSecrets?: boolean;
+    /** Idle time after which background samplers stop. Default 60000. */
+    inactivityTimeoutMs?: number;
+    /** TTL for mutation confirmation nonces. Default 60000. */
+    confirmTtlMs?: number;
+    /** Directory for heap snapshot files. Defaults to the OS temp dir. */
+    heapSnapshotDir?: string;
+}
+interface NodeUIServer {
+    readonly config: NodeUIConfig;
+    readonly active: boolean;
+    readonly activationReason: string;
+    /** Express/Nest compatible middleware that serves the console and API. */
+    middleware(): NodeUIMiddleware;
+    /** Direct request handling (no `next`); used for tests and adapters. */
+    handle(req: IncomingMessage, res: ServerResponse): Promise<void>;
+    /** Records a bootstrap timing mark, e.g. `mark("listening")`. */
+    mark(name: string): void;
+    /** Whether a background-sampling provider is currently running. */
+    isProviderActive(id: PanelId): boolean;
+    /** Pushes an external log entry into the log viewer (logger adapter). */
+    addLogSource(entry: {
+        level: LogLevel;
+        message: string;
+    }): void;
+    /** Stops all timers and background samplers. */
+    shutdown(): void;
+}
+type NodeUIMiddleware = (req: IncomingMessage, res: ServerResponse, next: () => void) => void;
+/**
+ * Serializes an API envelope to JSON, applying secret masking so values
+ * under keys like `TOKEN`/`KEY`/`SECRET`/`PASSWORD` never reach the UI.
+ */
+declare function serializeEnvelope<T>(envelope: ApiEnvelope<T>): string;
+declare function createNodeUI(options?: NodeUIOptions): NodeUIServer;
+
+export { type ActivationDecision, type ApiEnvelope, type ConfigData, type ConfirmIssued, ConfirmationStore, type CpuClock, type CpuData, CpuProvider, type CpuUsageSnapshot, DEFAULT_LOG_SIZE, type EnvData, type EnvEntry, EnvProvider, type EventLoopClock, EventLoopLagProvider, type EventLoopSample, type HealthData, HealthProvider, type HeapSnapshotData, type HeapSnapshotPanelData, HeapSnapshotProvider, type LogEntry, type LogLevel, type LogsData, LogsProvider, type MemoryData, MemoryProvider, type MetricsBucket, type MetricsData, MetricsProvider, type NodeUIConfig, type NodeUIMiddleware, type NodeUIOptions, type NodeUIProvider, type NodeUIServer, type PanelId, type ProviderContext, type ProviderError, ProviderRegistry, type ProviderResult, type RequestEntry, type RequestsData, RequestsProvider, RingBuffer, type RouteEntry, type RoutesData, RoutesProvider, SECRET_KEY_PATTERN, SECRET_MASKED, Sampler, type SamplerOptions, type SseStream, type StartupData, type StartupMark, StartupTracker, type StaticAsset, createNodeUI, extractRoutes, interceptConsole, isLoopbackAddress, maskSecrets, resolveActivation, resolveStaticAsset, serializeEnvelope, startSse };