@n-dx/web 0.1.0

package/dist/server/types.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Shared types for the web server.
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+/** Valid scope identifiers for standalone package viewers. */
+export type ViewerScope = "sourcevision" | "rex" | "hench";
+/** Server configuration passed to route handlers. */
+export interface ServerContext {
+    /** Absolute path to the project directory. */
+    projectDir: string;
+    /** Absolute path to .sourcevision/ directory. */
+    svDir: string;
+    /** Absolute path to .rex/ directory. */
+    rexDir: string;
+    /** Whether dev mode (live reload) is enabled. */
+    dev: boolean;
+    /** When set, restricts the dashboard to a single package's views and APIs. */
+    scope?: ViewerScope;
+}
+/** A route handler receives the request, response, and server context. */
+export type RouteHandler = (req: IncomingMessage, res: ServerResponse, ctx: ServerContext) => boolean | Promise<boolean>;
+/** JSON API response helper. */
+export declare function jsonResponse(res: ServerResponse, status: number, data: unknown): void;
+/** Plain-text error response helper. */
+export declare function errorResponse(res: ServerResponse, status: number, message: string): void;
+/** Read the full request body as a string. */
+export declare function readBody(req: IncomingMessage): Promise<string>;

package/dist/server/types.js

@@ -0,0 +1,26 @@
+/**
+ * Shared types for the web server.
+ */
+/** JSON API response helper. */
+export function jsonResponse(res, status, data) {
+    res.writeHead(status, {
+        "Content-Type": "application/json",
+        "Cache-Control": "no-cache",
+    });
+    res.end(JSON.stringify(data));
+}
+/** Plain-text error response helper. */
+export function errorResponse(res, status, message) {
+    res.writeHead(status, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ error: message }));
+}
+/** Read the full request body as a string. */
+export function readBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        req.on("data", (chunk) => chunks.push(chunk));
+        req.on("end", () => resolve(Buffer.concat(chunks).toString("utf-8")));
+        req.on("error", reject);
+    });
+}
+//# sourceMappingURL=types.js.map

package/dist/server/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/server/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AA4BH,gCAAgC;AAChC,MAAM,UAAU,YAAY,CAC1B,GAAmB,EACnB,MAAc,EACd,IAAa;IAEb,GAAG,CAAC,SAAS,CAAC,MAAM,EAAE;QACpB,cAAc,EAAE,kBAAkB;QAClC,eAAe,EAAE,UAAU;KAC5B,CAAC,CAAC;IACH,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC;AAChC,CAAC;AAED,wCAAwC;AACxC,MAAM,UAAU,aAAa,CAC3B,GAAmB,EACnB,MAAc,EACd,OAAe;IAEf,GAAG,CAAC,SAAS,CAAC,MAAM,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE,CAAC,CAAC;IAC9D,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC;AAC9C,CAAC;AAED,8CAA8C;AAC9C,MAAM,UAAU,QAAQ,CAAC,GAAoB;IAC3C,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,MAAM,MAAM,GAAa,EAAE,CAAC;QAC5B,GAAG,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;QACtD,GAAG,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;QACtE,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAC1B,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/server/usage-cleanup-scheduler.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Periodic cleanup scheduler for orphaned usage records.
+ *
+ * Cross-references in-memory usage aggregation with the current PRD state
+ * to identify and prune entries whose tasks no longer exist. Only prunes
+ * the in-memory aggregation cache — run files on disk are preserved as
+ * the source of truth, ensuring critical data survives PRD restructuring.
+ *
+ * ## Design
+ *
+ * The cleanup cycle:
+ *   1. Reads current aggregated task usage from the IncrementalTaskUsageAggregator
+ *   2. Loads valid task IDs from the PRD via `collectAllIds()`
+ *   3. Identifies orphaned entries (usage for tasks not in PRD)
+ *   4. Prunes them from the aggregator's in-memory state
+ *   5. Logs removed entries to a JSONL audit file for auditability
+ *   6. Broadcasts a WebSocket event so the dashboard can react
+ *
+ * Graceful degradation: if the PRD is unavailable (not initialized, corrupt,
+ * etc.), the cleanup cycle is skipped entirely — no data is removed.
+ *
+ * ## Configuration
+ *
+ * The cleanup interval is read from `.n-dx.json`:
+ * ```json
+ * { "cleanup": { "intervalMs": 604800000 } }
+ * ```
+ * Default: 604800000 ms (7 days / weekly).
+ *
+ * @module web/server/usage-cleanup-scheduler
+ */
+import type { IncrementalTaskUsageAggregator } from "./incremental-task-usage.js";
+import type { TaskUsageAccumulator, CollectAllIdsFn, OrphanedEntry, CleanupResult, CleanupLogEntry, CleanupConfig } from "./shared-types.js";
+export type { CollectAllIdsFn, OrphanedEntry, CleanupResult, CleanupLogEntry, CleanupConfig } from "./shared-types.js";
+/** Default cleanup interval: 7 days (weekly). */
+export declare const DEFAULT_CLEANUP_INTERVAL_MS: number;
+/**
+ * Identify orphaned usage entries by cross-referencing with valid PRD task IDs.
+ *
+ * Returns entries from `taskUsage` whose task IDs are not in `validTaskIds`.
+ * Pure function — no side effects.
+ */
+export declare function identifyOrphanedEntries(taskUsage: Record<string, TaskUsageAccumulator>, validTaskIds: Set<string>): OrphanedEntry[];
+/**
+ * Write a cleanup log entry to the JSONL audit file.
+ *
+ * Creates parent directories if they do not exist. Failures are silently
+ * swallowed — log writes are best-effort and must not break the cleanup cycle.
+ */
+export declare function writeCleanupLog(logPath: string, entry: CleanupLogEntry): void;
+/**
+ * Load cleanup configuration from `.n-dx.json`.
+ *
+ * Reads the `cleanup.intervalMs` key. Returns defaults for missing,
+ * malformed, or invalid configuration.
+ */
+export declare function loadCleanupConfig(projectDir: string): CleanupConfig;
+/** Signature for PRD loaders compatible with `loadPRDSync`. */
+export type LoadPRDFn = (rexDir: string) => unknown;
+/**
+ * Execute a single cleanup cycle.
+ *
+ * Cross-references current aggregated usage with the PRD to find orphaned
+ * entries, prunes them from the aggregator, and optionally logs and broadcasts
+ * the result.
+ *
+ * **Critical data preservation**: only in-memory aggregation state is pruned.
+ * Run files on disk (`.hench/runs/*.json`) are never modified or deleted,
+ * ensuring usage data can always be recovered via `aggregator.reset()`.
+ *
+ * @param options.aggregator The incremental task usage aggregator to clean
+ * @param options.rexDir Path to the `.rex/` directory containing `prd.json`
+ * @param options.collectAllIds Injected function to extract IDs from PRD items
+ * @param options.logPath Optional path for the JSONL audit log
+ * @param options.broadcast Optional WebSocket broadcast function
+ * @param options.loadPRD PRD loader function (injected to avoid cross-zone coupling; required when collectAllIds is provided)
+ */
+export declare function runCleanupCycle(options: {
+    aggregator: IncrementalTaskUsageAggregator;
+    rexDir: string;
+    collectAllIds?: CollectAllIdsFn;
+    logPath?: string;
+    broadcast?: (data: unknown) => void;
+    loadPRD?: LoadPRDFn;
+}): Promise<CleanupResult>;
+/**
+ * Start the periodic usage cleanup scheduler.
+ *
+ * Runs cleanup cycles on a configurable interval (read from `.n-dx.json`,
+ * default weekly). Each cycle cross-references usage data with the PRD
+ * and prunes orphaned entries.
+ *
+ * The returned interval handle should be stored in `watcherHandles.monitorIntervals`
+ * for proper cleanup during server shutdown.
+ *
+ * The timer is unref'd so it won't prevent process exit.
+ *
+ * @param ctx Server context with project paths
+ * @param getAggregator Factory to get the aggregator singleton for the runs directory
+ * @param broadcast Optional WebSocket broadcast function
+ * @param overrideIntervalMs Override interval (used for testing; takes precedence over config)
+ * @returns The setInterval handle
+ */
+export declare function startUsageCleanupScheduler(ctx: {
+    rexDir: string;
+    projectDir: string;
+}, getAggregator: () => IncrementalTaskUsageAggregator, broadcast?: (data: unknown) => void, overrideIntervalMs?: number, collectAllIds?: CollectAllIdsFn, loadPRD?: LoadPRDFn): ReturnType<typeof setInterval>;

package/dist/server/usage-cleanup-scheduler.js

@@ -0,0 +1,232 @@
+/**
+ * Periodic cleanup scheduler for orphaned usage records.
+ *
+ * Cross-references in-memory usage aggregation with the current PRD state
+ * to identify and prune entries whose tasks no longer exist. Only prunes
+ * the in-memory aggregation cache — run files on disk are preserved as
+ * the source of truth, ensuring critical data survives PRD restructuring.
+ *
+ * ## Design
+ *
+ * The cleanup cycle:
+ *   1. Reads current aggregated task usage from the IncrementalTaskUsageAggregator
+ *   2. Loads valid task IDs from the PRD via `collectAllIds()`
+ *   3. Identifies orphaned entries (usage for tasks not in PRD)
+ *   4. Prunes them from the aggregator's in-memory state
+ *   5. Logs removed entries to a JSONL audit file for auditability
+ *   6. Broadcasts a WebSocket event so the dashboard can react
+ *
+ * Graceful degradation: if the PRD is unavailable (not initialized, corrupt,
+ * etc.), the cleanup cycle is skipped entirely — no data is removed.
+ *
+ * ## Configuration
+ *
+ * The cleanup interval is read from `.n-dx.json`:
+ * ```json
+ * { "cleanup": { "intervalMs": 604800000 } }
+ * ```
+ * Default: 604800000 ms (7 days / weekly).
+ *
+ * @module web/server/usage-cleanup-scheduler
+ */
+import { readFileSync, appendFileSync, existsSync, mkdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Default cleanup interval: 7 days (weekly). */
+export const DEFAULT_CLEANUP_INTERVAL_MS = 7 * 24 * 60 * 60 * 1000;
+// ---------------------------------------------------------------------------
+// Pure functions
+// ---------------------------------------------------------------------------
+/**
+ * Identify orphaned usage entries by cross-referencing with valid PRD task IDs.
+ *
+ * Returns entries from `taskUsage` whose task IDs are not in `validTaskIds`.
+ * Pure function — no side effects.
+ */
+export function identifyOrphanedEntries(taskUsage, validTaskIds) {
+    const orphaned = [];
+    for (const [taskId, acc] of Object.entries(taskUsage)) {
+        if (!validTaskIds.has(taskId)) {
+            orphaned.push({
+                taskId,
+                totalTokens: acc.totalTokens,
+                runCount: acc.runCount,
+            });
+        }
+    }
+    return orphaned;
+}
+// ---------------------------------------------------------------------------
+// I/O helpers
+// ---------------------------------------------------------------------------
+/**
+ * Write a cleanup log entry to the JSONL audit file.
+ *
+ * Creates parent directories if they do not exist. Failures are silently
+ * swallowed — log writes are best-effort and must not break the cleanup cycle.
+ */
+export function writeCleanupLog(logPath, entry) {
+    try {
+        const dir = dirname(logPath);
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+        appendFileSync(logPath, JSON.stringify(entry) + "\n", "utf-8");
+    }
+    catch {
+        // Non-fatal: log write failure should not break cleanup
+    }
+}
+/**
+ * Load cleanup configuration from `.n-dx.json`.
+ *
+ * Reads the `cleanup.intervalMs` key. Returns defaults for missing,
+ * malformed, or invalid configuration.
+ */
+export function loadCleanupConfig(projectDir) {
+    const defaults = { intervalMs: DEFAULT_CLEANUP_INTERVAL_MS };
+    const configPath = join(projectDir, ".n-dx.json");
+    if (!existsSync(configPath))
+        return defaults;
+    try {
+        const raw = JSON.parse(readFileSync(configPath, "utf-8"));
+        const cleanup = raw.cleanup;
+        if (typeof cleanup !== "object" || cleanup === null)
+            return defaults;
+        const intervalMs = cleanup.intervalMs;
+        if (typeof intervalMs === "number" && intervalMs > 0) {
+            return { intervalMs };
+        }
+        return defaults;
+    }
+    catch {
+        return defaults;
+    }
+}
+/**
+ * Load valid task IDs from the PRD file.
+ *
+ * Returns null if the PRD cannot be read, allowing callers to degrade
+ * gracefully (skip cleanup rather than removing everything).
+ */
+function loadValidTaskIds(rexDir, collectAllIds, loadPRD) {
+    const doc = loadPRD(rexDir);
+    if (!doc || !Array.isArray(doc.items))
+        return null;
+    return collectAllIds(doc.items);
+}
+// ---------------------------------------------------------------------------
+// Core cleanup logic
+// ---------------------------------------------------------------------------
+/**
+ * Execute a single cleanup cycle.
+ *
+ * Cross-references current aggregated usage with the PRD to find orphaned
+ * entries, prunes them from the aggregator, and optionally logs and broadcasts
+ * the result.
+ *
+ * **Critical data preservation**: only in-memory aggregation state is pruned.
+ * Run files on disk (`.hench/runs/*.json`) are never modified or deleted,
+ * ensuring usage data can always be recovered via `aggregator.reset()`.
+ *
+ * @param options.aggregator The incremental task usage aggregator to clean
+ * @param options.rexDir Path to the `.rex/` directory containing `prd.json`
+ * @param options.collectAllIds Injected function to extract IDs from PRD items
+ * @param options.logPath Optional path for the JSONL audit log
+ * @param options.broadcast Optional WebSocket broadcast function
+ * @param options.loadPRD PRD loader function (injected to avoid cross-zone coupling; required when collectAllIds is provided)
+ */
+export async function runCleanupCycle(options) {
+    const { aggregator, rexDir, collectAllIds: collectIds, logPath, broadcast, loadPRD } = options;
+    // Ensure aggregator is populated before checking for orphans
+    const taskUsage = await aggregator.getTaskUsage();
+    const validIds = collectIds && loadPRD ? loadValidTaskIds(rexDir, collectIds, loadPRD) : null;
+    const result = {
+        timestamp: new Date().toISOString(),
+        prdAvailable: validIds !== null,
+        orphanedEntries: [],
+        totalOrphaned: 0,
+        totalTokensRemoved: 0,
+        totalRunsRemoved: 0,
+    };
+    // Skip cleanup if PRD is unavailable — we cannot determine which tasks
+    // are valid, so removing anything would risk data loss.
+    if (!validIds) {
+        return result;
+    }
+    const orphaned = identifyOrphanedEntries(taskUsage, validIds);
+    if (orphaned.length === 0) {
+        return result;
+    }
+    // Prune from aggregator's in-memory state
+    aggregator.pruneStaleEntries(validIds);
+    result.orphanedEntries = orphaned;
+    result.totalOrphaned = orphaned.length;
+    result.totalTokensRemoved = orphaned.reduce((sum, e) => sum + e.totalTokens, 0);
+    result.totalRunsRemoved = orphaned.reduce((sum, e) => sum + e.runCount, 0);
+    // Write audit log for accountability
+    if (logPath) {
+        writeCleanupLog(logPath, { event: "usage_cleanup", ...result });
+    }
+    // Broadcast so the dashboard knows cleanup occurred
+    if (broadcast) {
+        broadcast({
+            type: "hench:usage-cleanup",
+            ...result,
+        });
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
+// Scheduler
+// ---------------------------------------------------------------------------
+/**
+ * Start the periodic usage cleanup scheduler.
+ *
+ * Runs cleanup cycles on a configurable interval (read from `.n-dx.json`,
+ * default weekly). Each cycle cross-references usage data with the PRD
+ * and prunes orphaned entries.
+ *
+ * The returned interval handle should be stored in `watcherHandles.monitorIntervals`
+ * for proper cleanup during server shutdown.
+ *
+ * The timer is unref'd so it won't prevent process exit.
+ *
+ * @param ctx Server context with project paths
+ * @param getAggregator Factory to get the aggregator singleton for the runs directory
+ * @param broadcast Optional WebSocket broadcast function
+ * @param overrideIntervalMs Override interval (used for testing; takes precedence over config)
+ * @returns The setInterval handle
+ */
+export function startUsageCleanupScheduler(ctx, getAggregator, broadcast, overrideIntervalMs, collectAllIds, loadPRD) {
+    const logPath = join(ctx.projectDir, ".hench", "usage-cleanup.jsonl");
+    // Determine interval: explicit override > .n-dx.json config > default
+    const intervalMs = overrideIntervalMs ?? loadCleanupConfig(ctx.projectDir).intervalMs;
+    const timer = setInterval(async () => {
+        try {
+            const aggregator = getAggregator();
+            const result = await runCleanupCycle({
+                aggregator,
+                rexDir: ctx.rexDir,
+                collectAllIds,
+                logPath,
+                broadcast,
+                loadPRD,
+            });
+            if (result.totalOrphaned > 0) {
+                console.log(`[usage-cleanup] Removed ${result.totalOrphaned} orphaned task(s): ` +
+                    `${result.totalTokensRemoved} tokens across ${result.totalRunsRemoved} run(s)`);
+            }
+        }
+        catch (err) {
+            // Non-fatal: cleanup errors must not crash the server
+            console.error("[usage-cleanup] Error during cleanup cycle:", err);
+        }
+    }, intervalMs);
+    if (timer.unref) {
+        timer.unref();
+    }
+    return timer;
+}
+//# sourceMappingURL=usage-cleanup-scheduler.js.map

package/dist/server/usage-cleanup-scheduler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-cleanup-scheduler.js","sourceRoot":"","sources":["../../src/server/usage-cleanup-scheduler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAC9E,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAM1C,8EAA8E;AAC9E,YAAY;AACZ,8EAA8E;AAE9E,iDAAiD;AACjD,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAEnE,8EAA8E;AAC9E,iBAAiB;AACjB,8EAA8E;AAE9E;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CACrC,SAA+C,EAC/C,YAAyB;IAEzB,MAAM,QAAQ,GAAoB,EAAE,CAAC;IACrC,KAAK,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;QACtD,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;YAC9B,QAAQ,CAAC,IAAI,CAAC;gBACZ,MAAM;gBACN,WAAW,EAAE,GAAG,CAAC,WAAW;gBAC5B,QAAQ,EAAE,GAAG,CAAC,QAAQ;aACvB,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,8EAA8E;AAC9E,cAAc;AACd,8EAA8E;AAE9E;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,OAAe,EAAE,KAAsB;IACrE,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;QAC7B,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC1D,cAAc,CAAC,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,IAAI,EAAE,OAAO,CAAC,CAAC;IACjE,CAAC;IAAC,MAAM,CAAC;QACP,wDAAwD;IAC1D,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,UAAkB;IAClD,MAAM,QAAQ,GAAkB,EAAE,UAAU,EAAE,2BAA2B,EAAE,CAAC;IAE5E,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,EAAE,YAAY,CAAC,CAAC;IAClD,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC;QAAE,OAAO,QAAQ,CAAC;IAE7C,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,UAAU,EAAE,OAAO,CAAC,CAA4B,CAAC;QACrF,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC;QAC5B,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI;YAAE,OAAO,QAAQ,CAAC;QAErE,MAAM,UAAU,GAAI,OAAmC,CAAC,UAAU,CAAC;QACnE,IAAI,OAAO,UAAU,KAAK,QAAQ,IAAI,UAAU,GAAG,CAAC,EAAE,CAAC;YACrD,OAAO,EAAE,UAAU,EAAE,CAAC;QACxB,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,QAAQ,CAAC;IAClB,CAAC;AACH,CAAC;AAYD;;;;;GAKG;AACH,SAAS,gBAAgB,CACvB,MAAc,EACd,aAA8B,EAC9B,OAAkB;IAElB,MAAM,GAAG,GAAG,OAAO,CAAC,MAAM,CAAoB,CAAC;IAC/C,IAAI,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACnD,OAAO,aAAa,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;AAClC,CAAC;AAED,8EAA8E;AAC9E,qBAAqB;AACrB,8EAA8E;AAE9E;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,OAOrC;IACC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,aAAa,EAAE,UAAU,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;IAE/F,6DAA6D;IAC7D,MAAM,SAAS,GAAG,MAAM,UAAU,CAAC,YAAY,EAAE,CAAC;IAClD,MAAM,QAAQ,GAAG,UAAU,IAAI,OAAO,CAAC,CAAC,CAAC,gBAAgB,CAAC,MAAM,EAAE,UAAU,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAE9F,MAAM,MAAM,GAAkB;QAC5B,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACnC,YAAY,EAAE,QAAQ,KAAK,IAAI;QAC/B,eAAe,EAAE,EAAE;QACnB,aAAa,EAAE,CAAC;QAChB,kBAAkB,EAAE,CAAC;QACrB,gBAAgB,EAAE,CAAC;KACpB,CAAC;IAEF,uEAAuE;IACvE,wDAAwD;IACxD,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,MAAM,QAAQ,GAAG,uBAAuB,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;IAC9D,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,0CAA0C;IAC1C,UAAU,CAAC,iBAAiB,CAAC,QAAQ,CAAC,CAAC;IAEvC,MAAM,CAAC,eAAe,GAAG,QAAQ,CAAC;IAClC,MAAM,CAAC,aAAa,GAAG,QAAQ,CAAC,MAAM,CAAC;IACvC,MAAM,CAAC,kBAAkB,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC;IAChF,MAAM,CAAC,gBAAgB,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC;IAE3E,qCAAqC;IACrC,IAAI,OAAO,EAAE,CAAC;QACZ,eAAe,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,eAAe,EAAE,GAAG,MAAM,EAAE,CAAC,CAAC;IAClE,CAAC;IAED,oDAAoD;IACpD,IAAI,SAAS,EAAE,CAAC;QACd,SAAS,CAAC;YACR,IAAI,EAAE,qBAAqB;YAC3B,GAAG,MAAM;SACV,CAAC,CAAC;IACL,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,8EAA8E;AAC9E,YAAY;AACZ,8EAA8E;AAE9E;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,0BAA0B,CACxC,GAA2C,EAC3C,aAAmD,EACnD,SAAmC,EACnC,kBAA2B,EAC3B,aAA+B,EAC/B,OAAmB;IAEnB,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,UAAU,EAAE,QAAQ,EAAE,qBAAqB,CAAC,CAAC;IAEtE,sEAAsE;IACtE,MAAM,UAAU,GAAG,kBAAkB,IAAI,iBAAiB,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,UAAU,CAAC;IAEtF,MAAM,KAAK,GAAG,WAAW,CAAC,KAAK,IAAI,EAAE;QACnC,IAAI,CAAC;YACH,MAAM,UAAU,GAAG,aAAa,EAAE,CAAC;YACnC,MAAM,MAAM,GAAG,MAAM,eAAe,CAAC;gBACnC,UAAU;gBACV,MAAM,EAAE,GAAG,CAAC,MAAM;gBAClB,aAAa;gBACb,OAAO;gBACP,SAAS;gBACT,OAAO;aACR,CAAC,CAAC;YAEH,IAAI,MAAM,CAAC,aAAa,GAAG,CAAC,EAAE,CAAC;gBAC7B,OAAO,CAAC,GAAG,CACT,2BAA2B,MAAM,CAAC,aAAa,qBAAqB;oBACpE,GAAG,MAAM,CAAC,kBAAkB,kBAAkB,MAAM,CAAC,gBAAgB,SAAS,CAC/E,CAAC;YACJ,CAAC;QACH,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,sDAAsD;YACtD,OAAO,CAAC,KAAK,CAAC,6CAA6C,EAAE,GAAG,CAAC,CAAC;QACpE,CAAC;IACH,CAAC,EAAE,UAAU,CAAC,CAAC;IAEf,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;QAChB,KAAK,CAAC,KAAK,EAAE,CAAC;IAChB,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/server/websocket.d.ts

@@ -0,0 +1,131 @@
+/**
+ * WebSocket support for real-time updates.
+ *
+ * Implements the WebSocket protocol (RFC 6455) using only Node.js built-in
+ * modules — no external dependencies required.
+ *
+ * Supports:
+ * - Broadcasting PRD item changes to connected clients
+ * - Broadcasting file-change events (sourcevision data updates)
+ * - Immediate disconnect detection via socket events + pre-broadcast pruning
+ * - Ping/pong keepalive (reduced interval safety net)
+ * - Connection health tracking and lifecycle metrics
+ */
+import type { IncomingMessage } from "node:http";
+import type { Duplex } from "node:stream";
+/** Reason a client was removed from the connection set. */
+export type CleanupReason = "close" | "error" | "end" | "ping_timeout" | "prune" | "shutdown" | "write_fail";
+/** Health level derived from cleanup failure rate and connection trends. */
+export type WsHealthLevel = "healthy" | "degraded" | "unhealthy";
+/** Snapshot of WebSocket health metrics for API/broadcast consumption. */
+export interface WsHealthSnapshot {
+    /** Current number of active connections. */
+    activeConnections: number;
+    /** Peak concurrent connections seen since server start. */
+    peakConnections: number;
+    /** Total connections accepted since server start. */
+    totalConnectionsAccepted: number;
+    /** Total connections removed (for any reason) since server start. */
+    totalConnectionsRemoved: number;
+    /** Cleanup metrics broken down by reason. */
+    cleanupsByReason: Record<CleanupReason, number>;
+    /** Number of cleanups in the last 60 seconds. */
+    recentCleanups: number;
+    /** Average connection duration (ms) for connections closed in the last 5 minutes. */
+    avgConnectionDurationMs: number;
+    /** Total broadcasts sent since server start. */
+    totalBroadcasts: number;
+    /** Total failed writes during broadcasts. */
+    totalBroadcastWriteFailures: number;
+    /** Cleanup success rate (0–1): successful cleanups / total cleanups. */
+    cleanupSuccessRate: number;
+    /** Average cleanup timing (ms): how quickly dead connections are detected. */
+    avgCleanupLatencyMs: number;
+    /** Overall health level. */
+    health: WsHealthLevel;
+    /** Server uptime in milliseconds. */
+    uptimeMs: number;
+    /** ISO timestamp of this snapshot. */
+    timestamp: string;
+}
+/**
+ * WebSocket connection health tracker — records connection lifecycle events,
+ * cleanup metrics, and resource usage for dashboard monitoring.
+ *
+ * Instruments the WebSocket manager to collect:
+ * - Active vs total (historical peak) connection counts
+ * - Cleanup events: successful removals, reasons, timing
+ * - Broadcast statistics: total broadcasts, failed writes
+ * - Connection duration tracking
+ *
+ * Designed as a singleton that accumulates metrics over the server lifetime.
+ * Provides a snapshot API consumed by the REST endpoint and WS broadcast.
+ */
+export declare class WsHealthTracker {
+    private readonly startedAt;
+    private activeConnectionCount;
+    private peakConnectionCount;
+    private totalAccepted;
+    private totalRemoved;
+    private readonly connectionStartTimes;
+    private connectionIdCounter;
+    private readonly cleanupHistory;
+    private readonly cleanupsByReason;
+    private totalBroadcasts;
+    private totalWriteFailures;
+    private cleanupLatencySum;
+    private cleanupLatencyCount;
+    /**
+     * Record a new connection being accepted.
+     * Returns a connection ID to pass to `recordDisconnect()`.
+     */
+    recordConnect(): string;
+    /**
+     * Record a connection being removed.
+     */
+    recordDisconnect(connectionId: string, reason: CleanupReason): void;
+    /** Record a broadcast attempt. */
+    recordBroadcast(): void;
+    /** Record a failed write during broadcast. */
+    recordBroadcastWriteFailure(): void;
+    /**
+     * Sync the active connection count with the actual client set size.
+     * Called periodically to correct any drift from missed events.
+     */
+    syncActiveCount(actualCount: number): void;
+    /** Get a snapshot of current health metrics. */
+    getSnapshot(): WsHealthSnapshot;
+    /** Reset all counters (for testing). */
+    reset(): void;
+    private computeHealth;
+}
+/** A broadcast function that sends a message to all connected clients. */
+export type WebSocketBroadcaster = (data: unknown) => void;
+/** Options for the WebSocket manager. */
+export interface WebSocketManagerOptions {
+    /** Optional health tracker for connection lifecycle metrics. */
+    healthTracker?: WsHealthTracker;
+}
+/**
+ * Keepalive ping interval (ms). Reduced from 30 s for faster detection
+ * of silently dropped connections. Primary disconnect detection is
+ * event-driven (close/error/end handlers); pings are a safety net for
+ * connections that go silent without a TCP FIN/RST.
+ */
+export declare const PING_INTERVAL_MS = 5000;
+/**
+ * Create a WebSocket manager that handles upgrades and broadcasting.
+ *
+ * Usage:
+ * ```ts
+ * const ws = createWebSocketManager();
+ * server.on("upgrade", ws.handleUpgrade);
+ * ws.broadcast({ type: "rex:item-updated", itemId: "..." });
+ * ```
+ */
+export declare function createWebSocketManager(opts?: WebSocketManagerOptions): {
+    handleUpgrade: (req: IncomingMessage, socket: Duplex, head: Buffer) => void;
+    broadcast: WebSocketBroadcaster;
+    clientCount: () => number;
+    shutdown: () => void;
+};