@n-dx/core 0.1.0

package/packages/web/dist/server/domain-gateway.js

@@ -0,0 +1,19 @@
+/**
+ * Centralized gateway for sourcevision runtime imports.
+ *
+ * Web route handlers need the sourcevision MCP server factory to serve
+ * the `/mcp/sourcevision` endpoint. Rather than importing from "sourcevision"
+ * directly in route files, all web→sourcevision runtime imports pass through
+ * this single module.
+ *
+ * By concentrating all web→sourcevision runtime imports here, we ensure:
+ * - The cross-package surface is **explicit** (1 re-export, not scattered imports).
+ * - The DAG stays **acyclic** — sourcevision never imports from web.
+ * - Future changes to sourcevision's public API need only be updated here.
+ *
+ * @module web/server/domain-gateway
+ * @see packages/web/src/server/rex-gateway.ts — web's gateway for rex imports
+ * @see packages/hench/src/prd/rex-gateway.ts — hench's equivalent gateway
+ */
+export { createSourcevisionMcpServer } from "sourcevision";
+//# sourceMappingURL=domain-gateway.js.map

package/packages/web/dist/server/domain-gateway.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"domain-gateway.js","sourceRoot":"","sources":["../../src/server/domain-gateway.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,2BAA2B,EAAE,MAAM,cAAc,CAAC"}

package/packages/web/dist/server/incremental-task-usage.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Incremental task usage aggregator.
+ *
+ * Maintains an in-memory cache of per-task token usage aggregation.
+ * On each refresh, only processes new/modified run files using
+ * mtime+size change detection, keeping aggregation time constant
+ * regardless of total run history size.
+ *
+ * ## Design
+ *
+ * Each run file's contribution (taskId + totalTokens) is tracked
+ * individually so that modifications and deletions can be applied
+ * as incremental deltas rather than requiring a full re-scan.
+ *
+ * Change detection uses mtime + file size — the same strategy as
+ * hench's `RunChangeDetector` — to avoid reading unchanged files.
+ *
+ * @module web/server/incremental-task-usage
+ */
+import type { TaskUsageAccumulator } from "./shared-types.js";
+export type { TaskUsageAccumulator } from "./shared-types.js";
+/**
+ * Incrementally aggregates per-task token usage from `.hench/runs/` files.
+ *
+ * First call processes all existing run files (full scan). Subsequent calls
+ * detect filesystem changes via mtime+size comparison and only read the
+ * files that were added, modified, or deleted — keeping aggregation time
+ * constant regardless of total run history size.
+ *
+ * Usage:
+ * ```ts
+ * const aggregator = new IncrementalTaskUsageAggregator(runsDir);
+ * const usage = await aggregator.getTaskUsage();
+ * // { "task-123": { totalTokens: 5000, runCount: 2 }, ... }
+ * ```
+ */
+export declare class IncrementalTaskUsageAggregator {
+    private readonly runsDir;
+    /** Current snapshot of each file's mtime + size. */
+    private fileSnapshots;
+    /** Per-file contribution to the aggregation (for subtract-on-change). */
+    private fileContributions;
+    /** Aggregated usage per task ID. */
+    private taskUsage;
+    /** Whether the initial full scan has been completed. */
+    private initialized;
+    constructor(runsDir: string);
+    /**
+     * Get current per-task token usage, incrementally updating from filesystem.
+     *
+     * First call processes all files; subsequent calls only process changes.
+     * Returns a plain object keyed by task ID.
+     */
+    getTaskUsage(): Promise<Record<string, TaskUsageAccumulator>>;
+    /**
+     * Force a full rebuild on the next `getTaskUsage()` call.
+     * Useful for testing or when external state is known to have changed.
+     */
+    reset(): void;
+    /**
+     * Remove aggregation entries for task IDs not present in `validTaskIds`.
+     *
+     * Cleans up both the `taskUsage` accumulator and corresponding
+     * `fileContributions` entries. File snapshots are preserved so that
+     * the underlying run files are not re-processed on the next refresh
+     * (they are still on disk, just no longer contributing to results).
+     *
+     * Call this after `getTaskUsage()` — or let the route handler call it
+     * before returning results — to ensure the UI never sees usage data
+     * for tasks that have been deleted from the PRD.
+     *
+     * @returns The number of stale task IDs that were pruned.
+     */
+    pruneStaleEntries(validTaskIds: Set<string>): number;
+    private refresh;
+    /** Subtract a file's previously tracked contribution from the task total. */
+    private subtractContribution;
+    /** Add a file's contribution to the task total. */
+    private applyContribution;
+    /**
+     * Read a single run file (plain JSON or gzip-compressed) and extract
+     * its task usage contribution.
+     * Returns null for files that cannot be read or lack a taskId.
+     */
+    private readFileContribution;
+    /**
+     * Scan the runs directory and return a snapshot map of all run files
+     * (`.json` and `.json.gz`). Hidden files (prefixed with `.`) are
+     * excluded to avoid picking up checkpoint or metadata files.
+     */
+    private scanRunFiles;
+}

package/packages/web/dist/server/incremental-task-usage.js

@@ -0,0 +1,251 @@
+/**
+ * Incremental task usage aggregator.
+ *
+ * Maintains an in-memory cache of per-task token usage aggregation.
+ * On each refresh, only processes new/modified run files using
+ * mtime+size change detection, keeping aggregation time constant
+ * regardless of total run history size.
+ *
+ * ## Design
+ *
+ * Each run file's contribution (taskId + totalTokens) is tracked
+ * individually so that modifications and deletions can be applied
+ * as incremental deltas rather than requiring a full re-scan.
+ *
+ * Change detection uses mtime + file size — the same strategy as
+ * hench's `RunChangeDetector` — to avoid reading unchanged files.
+ *
+ * @module web/server/incremental-task-usage
+ */
+import { join } from "node:path";
+import { readFile, readdir, stat } from "node:fs/promises";
+import { gunzipSync } from "node:zlib";
+// ---------------------------------------------------------------------------
+// IncrementalTaskUsageAggregator
+// ---------------------------------------------------------------------------
+/**
+ * Incrementally aggregates per-task token usage from `.hench/runs/` files.
+ *
+ * First call processes all existing run files (full scan). Subsequent calls
+ * detect filesystem changes via mtime+size comparison and only read the
+ * files that were added, modified, or deleted — keeping aggregation time
+ * constant regardless of total run history size.
+ *
+ * Usage:
+ * ```ts
+ * const aggregator = new IncrementalTaskUsageAggregator(runsDir);
+ * const usage = await aggregator.getTaskUsage();
+ * // { "task-123": { totalTokens: 5000, runCount: 2 }, ... }
+ * ```
+ */
+export class IncrementalTaskUsageAggregator {
+    runsDir;
+    /** Current snapshot of each file's mtime + size. */
+    fileSnapshots = new Map();
+    /** Per-file contribution to the aggregation (for subtract-on-change). */
+    fileContributions = new Map();
+    /** Aggregated usage per task ID. */
+    taskUsage = new Map();
+    /** Whether the initial full scan has been completed. */
+    initialized = false;
+    constructor(runsDir) {
+        this.runsDir = runsDir;
+    }
+    /**
+     * Get current per-task token usage, incrementally updating from filesystem.
+     *
+     * First call processes all files; subsequent calls only process changes.
+     * Returns a plain object keyed by task ID.
+     */
+    async getTaskUsage() {
+        await this.refresh();
+        return Object.fromEntries(this.taskUsage);
+    }
+    /**
+     * Force a full rebuild on the next `getTaskUsage()` call.
+     * Useful for testing or when external state is known to have changed.
+     */
+    reset() {
+        this.fileSnapshots.clear();
+        this.fileContributions.clear();
+        this.taskUsage.clear();
+        this.initialized = false;
+    }
+    /**
+     * Remove aggregation entries for task IDs not present in `validTaskIds`.
+     *
+     * Cleans up both the `taskUsage` accumulator and corresponding
+     * `fileContributions` entries. File snapshots are preserved so that
+     * the underlying run files are not re-processed on the next refresh
+     * (they are still on disk, just no longer contributing to results).
+     *
+     * Call this after `getTaskUsage()` — or let the route handler call it
+     * before returning results — to ensure the UI never sees usage data
+     * for tasks that have been deleted from the PRD.
+     *
+     * @returns The number of stale task IDs that were pruned.
+     */
+    pruneStaleEntries(validTaskIds) {
+        // Identify stale task IDs
+        const staleIds = [];
+        for (const taskId of this.taskUsage.keys()) {
+            if (!validTaskIds.has(taskId)) {
+                staleIds.push(taskId);
+            }
+        }
+        if (staleIds.length === 0)
+            return 0;
+        const staleSet = new Set(staleIds);
+        // Remove from taskUsage
+        for (const taskId of staleIds) {
+            this.taskUsage.delete(taskId);
+        }
+        // Remove matching fileContributions (but keep fileSnapshots so
+        // the run files are not treated as "new" on the next refresh)
+        for (const [file, contribution] of this.fileContributions) {
+            if (staleSet.has(contribution.taskId)) {
+                this.fileContributions.delete(file);
+            }
+        }
+        return staleIds.length;
+    }
+    // ---- Core refresh logic --------------------------------------------------
+    async refresh() {
+        const currentFiles = await this.scanRunFiles();
+        // Categorize changes
+        const added = [];
+        const modified = [];
+        const deleted = [];
+        for (const [file, snapshot] of currentFiles) {
+            const prev = this.fileSnapshots.get(file);
+            if (!prev) {
+                added.push(file);
+            }
+            else if (prev.mtimeMs !== snapshot.mtimeMs || prev.size !== snapshot.size) {
+                modified.push(file);
+            }
+        }
+        for (const file of this.fileSnapshots.keys()) {
+            if (!currentFiles.has(file)) {
+                deleted.push(file);
+            }
+        }
+        // Short-circuit: no changes after initial scan
+        if (this.initialized && added.length === 0 && modified.length === 0 && deleted.length === 0) {
+            return;
+        }
+        // Process deletions: subtract old contributions
+        for (const file of deleted) {
+            this.subtractContribution(file);
+            this.fileSnapshots.delete(file);
+        }
+        // Process modifications: subtract old → re-read → add new
+        for (const file of modified) {
+            this.subtractContribution(file);
+            const contribution = await this.readFileContribution(file);
+            if (contribution) {
+                this.applyContribution(file, contribution);
+            }
+            this.fileSnapshots.set(file, currentFiles.get(file));
+        }
+        // Process additions: read and add
+        for (const file of added) {
+            const contribution = await this.readFileContribution(file);
+            if (contribution) {
+                this.applyContribution(file, contribution);
+            }
+            this.fileSnapshots.set(file, currentFiles.get(file));
+        }
+        this.initialized = true;
+    }
+    // ---- Contribution tracking -----------------------------------------------
+    /** Subtract a file's previously tracked contribution from the task total. */
+    subtractContribution(file) {
+        const contribution = this.fileContributions.get(file);
+        if (!contribution)
+            return;
+        const current = this.taskUsage.get(contribution.taskId);
+        if (current) {
+            current.totalTokens -= contribution.totalTokens;
+            current.runCount -= 1;
+            if (current.runCount <= 0) {
+                this.taskUsage.delete(contribution.taskId);
+            }
+        }
+        this.fileContributions.delete(file);
+    }
+    /** Add a file's contribution to the task total. */
+    applyContribution(file, contribution) {
+        this.fileContributions.set(file, contribution);
+        const current = this.taskUsage.get(contribution.taskId) ?? { totalTokens: 0, runCount: 0 };
+        current.totalTokens += contribution.totalTokens;
+        current.runCount += 1;
+        this.taskUsage.set(contribution.taskId, current);
+    }
+    // ---- File I/O ------------------------------------------------------------
+    /**
+     * Read a single run file (plain JSON or gzip-compressed) and extract
+     * its task usage contribution.
+     * Returns null for files that cannot be read or lack a taskId.
+     */
+    async readFileContribution(file) {
+        try {
+            let data;
+            if (file.endsWith(".gz")) {
+                const compressed = await readFile(join(this.runsDir, file));
+                const decompressed = gunzipSync(compressed);
+                data = JSON.parse(decompressed.toString("utf-8"));
+            }
+            else {
+                const raw = await readFile(join(this.runsDir, file), "utf-8");
+                data = JSON.parse(raw);
+            }
+            const taskId = data.taskId;
+            if (typeof taskId !== "string" || !taskId)
+                return null;
+            const tokenUsage = data.tokenUsage;
+            const totalTokens = (tokenUsage?.input ?? 0) +
+                (tokenUsage?.output ?? 0) +
+                (tokenUsage?.cacheCreationInput ?? 0) +
+                (tokenUsage?.cacheReadInput ?? 0);
+            return { taskId, totalTokens };
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Scan the runs directory and return a snapshot map of all run files
+     * (`.json` and `.json.gz`). Hidden files (prefixed with `.`) are
+     * excluded to avoid picking up checkpoint or metadata files.
+     */
+    async scanRunFiles() {
+        const snapshots = new Map();
+        let files;
+        try {
+            files = await readdir(this.runsDir);
+        }
+        catch {
+            return snapshots;
+        }
+        const runFiles = files.filter((f) => (f.endsWith(".json") || f.endsWith(".json.gz")) && !f.startsWith("."));
+        // Stat files in parallel for performance
+        const entries = await Promise.all(runFiles.map(async (file) => {
+            try {
+                const st = await stat(join(this.runsDir, file));
+                return { file, snapshot: { mtimeMs: st.mtimeMs, size: st.size } };
+            }
+            catch {
+                // File disappeared between readdir and stat — skip
+                return null;
+            }
+        }));
+        for (const entry of entries) {
+            if (entry) {
+                snapshots.set(entry.file, entry.snapshot);
+            }
+        }
+        return snapshots;
+    }
+}
+//# sourceMappingURL=incremental-task-usage.js.map

package/packages/web/dist/server/incremental-task-usage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"incremental-task-usage.js","sourceRoot":"","sources":["../../src/server/incremental-task-usage.ts"],"names":[],"mappings":"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"}

package/packages/web/dist/server/index.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Web server for the n-dx dashboard.
+ *
+ * Serves the sourcevision viewer, provides REST API endpoints for
+ * Rex (PRD data), sourcevision (analysis data), and Hench (agent runs),
+ * and supports WebSocket connections for real-time updates.
+ *
+ * ## Route architecture
+ *
+ * ```
+ *   Static assets   → routes-static.ts
+ *   /data/*          → routes-data.ts         (sourcevision data files, live-reload)
+ *   /api/rex/*       → routes-rex.ts          (PRD CRUD, stats, next task, log)
+ *   /api/sv/*        → routes-sourcevision.ts (analysis data endpoints)
+ *   /api/hench/*     → routes-hench.ts        (agent run history, run detail)
+ *   /mcp/rex         → routes-mcp.ts          (Rex MCP over Streamable HTTP)
+ *   /mcp/sourcevision→ routes-mcp.ts          (Sourcevision MCP over Streamable HTTP)
+ *   WebSocket        → websocket.ts           (upgrade handler, broadcast)
+ * ```
+ *
+ * ## Coupling strategy
+ *
+ * REST/API routes access domain data through **filesystem reads** and
+ * **subprocess calls**.  Rex domain types and constants are imported from
+ * the canonical source through the gateway (`domain-gateway.ts`), eliminating
+ * the previous duplication in `rex-domain.ts`.
+ *
+ * MCP server factories and rex domain constants are funnelled through
+ * `domain-gateway.ts` — a single gateway module that mirrors the pattern
+ * in `packages/hench/src/prd/rex-gateway.ts`.
+ *
+ * @see ./domain-gateway.ts — runtime import gateway (all cross-package imports)
+ */
+export { startServer, PORT_FILE } from "./start.js";
+export type { ServerOptions, StartResult } from "./start.js";
+export type { ServerContext, RouteHandler } from "./types.js";
+export type { WebSocketBroadcaster } from "./websocket.js";
+export { checkPort, checkPortWithRetry, findAvailablePort } from "./port.js";
+export type { PortCheckResult, PortAllocationResult, PortRetryOptions } from "./port.js";

package/packages/web/dist/server/index.js

@@ -0,0 +1,36 @@
+/**
+ * Web server for the n-dx dashboard.
+ *
+ * Serves the sourcevision viewer, provides REST API endpoints for
+ * Rex (PRD data), sourcevision (analysis data), and Hench (agent runs),
+ * and supports WebSocket connections for real-time updates.
+ *
+ * ## Route architecture
+ *
+ * ```
+ *   Static assets   → routes-static.ts
+ *   /data/*          → routes-data.ts         (sourcevision data files, live-reload)
+ *   /api/rex/*       → routes-rex.ts          (PRD CRUD, stats, next task, log)
+ *   /api/sv/*        → routes-sourcevision.ts (analysis data endpoints)
+ *   /api/hench/*     → routes-hench.ts        (agent run history, run detail)
+ *   /mcp/rex         → routes-mcp.ts          (Rex MCP over Streamable HTTP)
+ *   /mcp/sourcevision→ routes-mcp.ts          (Sourcevision MCP over Streamable HTTP)
+ *   WebSocket        → websocket.ts           (upgrade handler, broadcast)
+ * ```
+ *
+ * ## Coupling strategy
+ *
+ * REST/API routes access domain data through **filesystem reads** and
+ * **subprocess calls**.  Rex domain types and constants are imported from
+ * the canonical source through the gateway (`domain-gateway.ts`), eliminating
+ * the previous duplication in `rex-domain.ts`.
+ *
+ * MCP server factories and rex domain constants are funnelled through
+ * `domain-gateway.ts` — a single gateway module that mirrors the pattern
+ * in `packages/hench/src/prd/rex-gateway.ts`.
+ *
+ * @see ./domain-gateway.ts — runtime import gateway (all cross-package imports)
+ */
+export { startServer, PORT_FILE } from "./start.js";
+export { checkPort, checkPortWithRetry, findAvailablePort } from "./port.js";
+//# sourceMappingURL=index.js.map

package/packages/web/dist/server/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAIpD,OAAO,EAAE,SAAS,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC"}

package/packages/web/dist/server/mcp-deps.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @deprecated Use `rex-gateway.ts` for Rex imports and `domain-gateway.ts`
+ * for Sourcevision MCP imports.
+ */
+export * from "./rex-gateway.js";
+export * from "./domain-gateway.js";

package/packages/web/dist/server/mcp-deps.js

@@ -0,0 +1,7 @@
+/**
+ * @deprecated Use `rex-gateway.ts` for Rex imports and `domain-gateway.ts`
+ * for Sourcevision MCP imports.
+ */
+export * from "./rex-gateway.js";
+export * from "./domain-gateway.js";
+//# sourceMappingURL=mcp-deps.js.map

package/packages/web/dist/server/mcp-deps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-deps.js","sourceRoot":"","sources":["../../src/server/mcp-deps.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC"}

package/packages/web/dist/server/port.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Port availability detection and dynamic allocation.
+ *
+ * Provides utilities for checking whether a TCP port is available and
+ * finding the next available port within a configurable range.
+ *
+ * Used by the server startup code to gracefully fall back when the
+ * configured port (default 3117) is already occupied.
+ */
+/** Default port range for fallback allocation. */
+export declare const DEFAULT_PORT = 3117;
+export declare const PORT_RANGE_START = 3117;
+export declare const PORT_RANGE_END = 3200;
+export interface PortCheckResult {
+    /** Whether the requested port is available. */
+    available: boolean;
+    /** The port that was checked. */
+    port: number;
+    /** Error details if the port is unavailable (e.g. "EADDRINUSE", "EACCES"). */
+    error?: string;
+}
+export interface PortAllocationResult {
+    /** The port that is available and should be used. */
+    port: number;
+    /** Whether this is the originally requested port (true) or a fallback (false). */
+    isOriginal: boolean;
+    /** The originally requested port. */
+    requestedPort: number;
+}
+/**
+ * Options controlling the retry behaviour of {@link checkPortWithRetry}
+ * and the preferred-port phase of {@link findAvailablePort}.
+ */
+export interface PortRetryOptions {
+    /**
+     * Maximum number of retries after the first failure.
+     * @default 5
+     */
+    maxRetries?: number;
+    /**
+     * Initial delay between retries in milliseconds.
+     * Subsequent delays grow by `backoffFactor` (exponential backoff).
+     * @default 100
+     */
+    retryDelayMs?: number;
+    /**
+     * Multiplier applied to the delay after each retry attempt.
+     * A value of `2` doubles the delay each time.
+     * @default 2
+     */
+    backoffFactor?: number;
+}
+/**
+ * Check if a specific port is available for binding.
+ *
+ * Uses a two-phase approach:
+ * 1. Try to connect — if something is already listening, report unavailable.
+ * 2. If nothing is listening, try to bind — catches EACCES and other bind errors.
+ *
+ * This avoids SO_REUSEADDR false positives where a bind-only check might
+ * succeed even though the port is already occupied by another process.
+ */
+export declare function checkPort(port: number): Promise<PortCheckResult>;
+/**
+ * Check if a port is available, retrying on transient failures.
+ *
+ * Wraps {@link checkPort} with a configurable retry loop to handle timing
+ * issues during process transitions.  When a server has just been stopped, its
+ * port may remain in OS TIME_WAIT state for a short period and appear
+ * unavailable even though no process is actively listening.  Retrying with
+ * exponential back-off gives the OS time to release the port without forcing
+ * the caller to fall back to a different port number.
+ *
+ * Retries are skipped immediately for non-transient errors such as `EACCES`
+ * (permission denied), since those require external intervention and will
+ * not resolve on their own.
+ *
+ * @param port  TCP port number to check.
+ * @param opts  Retry configuration.  Defaults suit most startup scenarios.
+ */
+export declare function checkPortWithRetry(port: number, opts?: PortRetryOptions): Promise<PortCheckResult>;
+/**
+ * Find the next available port in a range.
+ *
+ * Tries the `preferred` port first (with optional retries to handle transient
+ * unavailability during process transitions), then scans sequentially from
+ * `rangeStart` to `rangeEnd` (inclusive). Skips the preferred port during the
+ * scan since it was already tried.
+ *
+ * Pass `retryOpts` to give the preferred port several retry attempts before
+ * falling back to the range scan.  This is useful when the preferred port was
+ * just released by a recently stopped server (TIME_WAIT state).
+ *
+ * @throws {Error} If no port is available in the entire range.
+ */
+export declare function findAvailablePort(preferred: number, rangeStart?: number, rangeEnd?: number, retryOpts?: PortRetryOptions): Promise<PortAllocationResult>;