@n-dx/web 0.1.0

package/dist/server/search-index.js

@@ -0,0 +1,348 @@
+/**
+ * In-memory search index for PRD items.
+ *
+ * Builds an inverted index from PRD item titles, descriptions, acceptance
+ * criteria, and tags. Supports fuzzy/partial matching, exact phrase matching
+ * with quotes, multi-word AND/OR queries, and relevance-weighted scoring
+ * (title matches rank higher than descriptions).
+ *
+ * The index is lazy — built on first search — and auto-invalidated when the
+ * PRD file changes (checked via mtime on each search request).
+ *
+ * @module web/server/search-index
+ */
+import { statSync } from "node:fs";
+import { join } from "node:path";
+import { walkTree } from "./rex-gateway.js";
+import { loadPRDSync } from "./prd-io.js";
+// ── Field weights ──────────────────────────────────────────────────────────
+/** Relevance weights per field — title matches score highest. */
+const FIELD_WEIGHTS = {
+    title: 10,
+    tags: 6,
+    description: 3,
+    acceptanceCriteria: 2,
+};
+// ── Stop words (minimal set to avoid removing meaningful search terms) ─────
+const STOP_WORDS = new Set([
+    "a", "an", "the", "is", "are", "was", "were", "be", "been", "being",
+    "have", "has", "had", "do", "does", "did", "will", "would", "shall",
+    "should", "may", "might", "must", "can", "could",
+    "and", "but", "or", "nor", "not", "so", "if", "then",
+    "for", "in", "on", "at", "to", "of", "by", "with", "from",
+]);
+// ── Query parsing ──────────────────────────────────────────────────────────
+/**
+ * Parse a raw query string into structured components.
+ *
+ * Supports:
+ * - `"exact phrase"` — quoted segments for exact phrase matching
+ * - `word1 word2` — AND logic (all words must match) by default
+ * - `word1 OR word2` — OR logic when "OR" appears between terms
+ * - Case insensitive
+ */
+export function parseQuery(raw) {
+    const phrases = [];
+    let remaining = raw;
+    // Extract quoted phrases
+    const quotePattern = /"([^"]+)"/g;
+    let match;
+    while ((match = quotePattern.exec(raw)) !== null) {
+        const phrase = match[1].trim().toLowerCase();
+        if (phrase.length > 0) {
+            phrases.push(phrase);
+        }
+    }
+    remaining = remaining.replace(quotePattern, " ").trim();
+    // Detect OR logic: if "OR" appears as a standalone word (case-sensitive)
+    const isOr = /\bOR\b/.test(remaining);
+    remaining = remaining.replace(/\bOR\b/g, " ");
+    // Tokenize remaining terms
+    const terms = remaining
+        .toLowerCase()
+        .replace(/[^a-z0-9\s\-_]/g, " ")
+        .split(/\s+/)
+        .filter((t) => t.length > 0 && !STOP_WORDS.has(t));
+    return { phrases, terms, isOr };
+}
+// ── Tokenizer ──────────────────────────────────────────────────────────────
+/** Tokenize a text string into lowercase alphanumeric tokens. */
+function tokenize(text) {
+    return text
+        .toLowerCase()
+        .replace(/[^a-z0-9\s\-_]/g, " ")
+        .split(/\s+/)
+        .filter((t) => t.length > 0);
+}
+// ── SearchIndex class ──────────────────────────────────────────────────────
+export class SearchIndex {
+    /** Inverted index: term → list of (itemId, field, position). */
+    invertedIndex = new Map();
+    /** Full indexed items keyed by ID. */
+    items = new Map();
+    /** Lowercased full-text per field per item for phrase matching. */
+    fieldText = new Map();
+    /** File mtime when the index was last built (for staleness check). */
+    builtAtMtime = 0;
+    /** Path to prd.json (set once). */
+    prdPath;
+    /** Rex directory path for centralized PRD loading. */
+    rexDir;
+    constructor(rexDir) {
+        this.rexDir = rexDir;
+        this.prdPath = join(rexDir, "prd.json");
+    }
+    // ── Public API ─────────────────────────────────────────────────────────
+    /**
+     * Search the index with the given raw query string.
+     *
+     * Automatically rebuilds the index if the PRD file has changed since the
+     * last build. Returns results sorted by relevance score descending.
+     */
+    search(query, limit = 50) {
+        this.ensureFresh();
+        const parsed = parseQuery(query);
+        if (parsed.terms.length === 0 && parsed.phrases.length === 0) {
+            return [];
+        }
+        // Score each item
+        const scores = new Map();
+        // Score term matches (supports partial/fuzzy prefix matching)
+        for (const term of parsed.terms) {
+            const termHits = this.findTermMatches(term);
+            for (const hit of termHits) {
+                let entry = scores.get(hit.id);
+                if (!entry) {
+                    entry = { score: 0, matchedFields: new Set() };
+                    scores.set(hit.id, entry);
+                }
+                entry.score += FIELD_WEIGHTS[hit.field] ?? 1;
+                entry.matchedFields.add(hit.field);
+            }
+        }
+        // Score phrase matches
+        for (const phrase of parsed.phrases) {
+            for (const [id, fields] of this.fieldText) {
+                for (const [field, text] of fields) {
+                    if (text.includes(phrase)) {
+                        let entry = scores.get(id);
+                        if (!entry) {
+                            entry = { score: 0, matchedFields: new Set() };
+                            scores.set(id, entry);
+                        }
+                        // Phrases are worth more — they indicate exact intent
+                        entry.score += (FIELD_WEIGHTS[field] ?? 1) * 2;
+                        entry.matchedFields.add(field);
+                    }
+                }
+            }
+        }
+        // Apply AND/OR filtering
+        const results = [];
+        const totalQueryParts = parsed.terms.length + parsed.phrases.length;
+        for (const [id, { score, matchedFields }] of scores) {
+            const item = this.items.get(id);
+            if (!item)
+                continue;
+            if (!parsed.isOr && totalQueryParts > 1) {
+                // AND mode: verify all terms and phrases matched
+                const matchedParts = this.countMatchedParts(id, parsed);
+                if (matchedParts < totalQueryParts)
+                    continue;
+            }
+            results.push({
+                id: item.id,
+                title: item.title,
+                description: item.description || null,
+                level: item.level,
+                status: item.status,
+                parentChain: item.parentChain,
+                score,
+                matchedFields: [...matchedFields],
+            });
+        }
+        // Sort by score descending
+        results.sort((a, b) => {
+            if (a.score !== b.score)
+                return b.score - a.score;
+            // Tiebreak: title match first, then alphabetical
+            const aTitle = a.matchedFields.includes("title") ? 0 : 1;
+            const bTitle = b.matchedFields.includes("title") ? 0 : 1;
+            if (aTitle !== bTitle)
+                return aTitle - bTitle;
+            return a.title.localeCompare(b.title);
+        });
+        return results.slice(0, limit);
+    }
+    /**
+     * Force a rebuild of the index from the current PRD file.
+     * Returns the number of items indexed.
+     */
+    rebuild() {
+        this.invertedIndex.clear();
+        this.items.clear();
+        this.fieldText.clear();
+        const doc = this.loadPRD();
+        if (!doc) {
+            this.builtAtMtime = 0;
+            return 0;
+        }
+        // Walk the tree and index every item
+        for (const { item, parents } of walkTree(doc.items)) {
+            this.indexItem(item, parents);
+        }
+        // Record the mtime we built from
+        this.builtAtMtime = this.getPrdMtime();
+        return this.items.size;
+    }
+    /** Invalidate the cached index, forcing a rebuild on next search. */
+    invalidate() {
+        this.builtAtMtime = 0;
+    }
+    /** Number of items currently in the index. */
+    get size() {
+        return this.items.size;
+    }
+    /** Number of unique terms in the inverted index. */
+    get termCount() {
+        return this.invertedIndex.size;
+    }
+    // ── Internal ───────────────────────────────────────────────────────────
+    /** Ensure the index is fresh by checking PRD file mtime. */
+    ensureFresh() {
+        const currentMtime = this.getPrdMtime();
+        if (currentMtime !== this.builtAtMtime || this.builtAtMtime === 0) {
+            this.rebuild();
+        }
+    }
+    /** Get the PRD file modification time (0 if file doesn't exist). */
+    getPrdMtime() {
+        try {
+            return statSync(this.prdPath).mtimeMs;
+        }
+        catch {
+            return 0;
+        }
+    }
+    /** Load the PRD document from disk. */
+    loadPRD() {
+        return loadPRDSync(this.rexDir);
+    }
+    /** Index a single PRD item. */
+    indexItem(item, parents) {
+        const indexed = {
+            id: item.id,
+            title: item.title,
+            description: item.description ?? "",
+            level: item.level,
+            status: item.status,
+            tags: item.tags ?? [],
+            acceptanceCriteria: (item.acceptanceCriteria ?? []).join(" "),
+            parentChain: parents.map((p) => p.title),
+        };
+        this.items.set(item.id, indexed);
+        // Build per-field lowercased text for phrase matching
+        const fields = new Map();
+        fields.set("title", indexed.title.toLowerCase());
+        fields.set("description", indexed.description.toLowerCase());
+        fields.set("acceptanceCriteria", indexed.acceptanceCriteria.toLowerCase());
+        fields.set("tags", indexed.tags.join(" ").toLowerCase());
+        this.fieldText.set(item.id, fields);
+        // Tokenize and add to inverted index
+        this.addTokens(item.id, "title", tokenize(indexed.title));
+        this.addTokens(item.id, "description", tokenize(indexed.description));
+        this.addTokens(item.id, "acceptanceCriteria", tokenize(indexed.acceptanceCriteria));
+        this.addTokens(item.id, "tags", tokenize(indexed.tags.join(" ")));
+    }
+    /** Add tokens to the inverted index for a specific item and field. */
+    addTokens(id, field, tokens) {
+        for (let i = 0; i < tokens.length; i++) {
+            const token = tokens[i];
+            let entries = this.invertedIndex.get(token);
+            if (!entries) {
+                entries = [];
+                this.invertedIndex.set(token, entries);
+            }
+            entries.push({ id, field, position: i });
+        }
+    }
+    /**
+     * Find all items that match a term, supporting prefix/partial matching.
+     * Returns deduplicated hits (one per item-field combination).
+     */
+    findTermMatches(term) {
+        const results = [];
+        const seen = new Set();
+        // Exact match
+        const exact = this.invertedIndex.get(term);
+        if (exact) {
+            for (const entry of exact) {
+                const key = `${entry.id}:${entry.field}`;
+                if (!seen.has(key)) {
+                    seen.add(key);
+                    results.push(entry);
+                }
+            }
+        }
+        // Prefix match — find all terms that start with the search term
+        // (only if term is at least 3 chars to avoid too many partial matches)
+        if (term.length >= 3) {
+            for (const [indexedTerm, entries] of this.invertedIndex) {
+                if (indexedTerm !== term && indexedTerm.startsWith(term)) {
+                    for (const entry of entries) {
+                        const key = `${entry.id}:${entry.field}`;
+                        if (!seen.has(key)) {
+                            seen.add(key);
+                            // Partial matches score slightly less
+                            results.push({ ...entry });
+                        }
+                    }
+                }
+            }
+        }
+        // Substring match — for "fuzzy" matching, check if any indexed term
+        // contains the search term (only for terms >= 4 chars)
+        if (term.length >= 4) {
+            for (const [indexedTerm, entries] of this.invertedIndex) {
+                if (indexedTerm !== term && !indexedTerm.startsWith(term) && indexedTerm.includes(term)) {
+                    for (const entry of entries) {
+                        const key = `${entry.id}:${entry.field}`;
+                        if (!seen.has(key)) {
+                            seen.add(key);
+                            results.push({ ...entry });
+                        }
+                    }
+                }
+            }
+        }
+        return results;
+    }
+    /**
+     * Count how many distinct query parts (terms + phrases) matched for an item.
+     * Used for AND logic filtering.
+     */
+    countMatchedParts(id, parsed) {
+        let matched = 0;
+        // Check terms
+        for (const term of parsed.terms) {
+            const hits = this.findTermMatches(term);
+            if (hits.some((h) => h.id === id)) {
+                matched++;
+            }
+        }
+        // Check phrases
+        const fields = this.fieldText.get(id);
+        if (fields) {
+            for (const phrase of parsed.phrases) {
+                for (const text of fields.values()) {
+                    if (text.includes(phrase)) {
+                        matched++;
+                        break; // Count each phrase once
+                    }
+                }
+            }
+        }
+        return matched;
+    }
+}
+//# sourceMappingURL=search-index.js.map

package/dist/server/search-index.js.map

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

package/dist/server/shared-types.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Neutral type definitions shared across server zones.
+ *
+ * This module breaks dependency cycles between the task-usage-analytics
+ * and web-dashboard zones by providing a single, zone-neutral home for
+ * types that both zones reference. Without this file, types like
+ * `CollectAllIdsFn` and `TaskUsageAccumulator` create implicit coupling
+ * when one zone defines them and the other imports them directly.
+ *
+ * ## Stability contract
+ *
+ * **@public** — These types form the cross-zone analytics contract.
+ * Breaking changes (field renames, type narrowing, removal) require
+ * coordinated updates in all consuming files:
+ *   - task-usage.ts, incremental-task-usage.ts (task-usage-analytics zone)
+ *   - usage-cleanup-scheduler.ts, register-scheduler.ts (web-dashboard zone)
+ *   - public.ts (package public API)
+ *
+ * Add new types freely. Modify existing types only with a grep for all
+ * import sites in `packages/web/src/server/`.
+ *
+ * Rules:
+ * - Types only — no runtime code, no side effects.
+ * - Both zones import FROM here; neither zone re-exports these types.
+ * - New cross-zone types should be added here rather than in leaf files.
+ *
+ * @public
+ * @module web/server/shared-types
+ */
+/** Aggregated token usage for a single task. */
+export interface TaskUsageAccumulator {
+    totalTokens: number;
+    runCount: number;
+}
+/**
+ * Callback that extracts valid task IDs from a flat array of PRD items.
+ *
+ * Injected by the caller to avoid a direct import of rex-gateway in the
+ * cleanup zone, which would create a bidirectional dependency cycle.
+ */
+export type CollectAllIdsFn = (items: unknown[]) => Set<string>;
+/** A single orphaned usage entry identified during cleanup. */
+export interface OrphanedEntry {
+    taskId: string;
+    totalTokens: number;
+    runCount: number;
+}
+/** Result of a single cleanup cycle. */
+export interface CleanupResult {
+    timestamp: string;
+    prdAvailable: boolean;
+    orphanedEntries: OrphanedEntry[];
+    totalOrphaned: number;
+    totalTokensRemoved: number;
+    totalRunsRemoved: number;
+}
+/** Persistent log entry written to the cleanup JSONL audit file. */
+export interface CleanupLogEntry extends CleanupResult {
+    event: "usage_cleanup";
+}
+/** Cleanup configuration read from `.n-dx.json`. */
+export interface CleanupConfig {
+    /** Cleanup interval in milliseconds. */
+    intervalMs: number;
+}

package/dist/server/shared-types.js

@@ -0,0 +1,31 @@
+/**
+ * Neutral type definitions shared across server zones.
+ *
+ * This module breaks dependency cycles between the task-usage-analytics
+ * and web-dashboard zones by providing a single, zone-neutral home for
+ * types that both zones reference. Without this file, types like
+ * `CollectAllIdsFn` and `TaskUsageAccumulator` create implicit coupling
+ * when one zone defines them and the other imports them directly.
+ *
+ * ## Stability contract
+ *
+ * **@public** — These types form the cross-zone analytics contract.
+ * Breaking changes (field renames, type narrowing, removal) require
+ * coordinated updates in all consuming files:
+ *   - task-usage.ts, incremental-task-usage.ts (task-usage-analytics zone)
+ *   - usage-cleanup-scheduler.ts, register-scheduler.ts (web-dashboard zone)
+ *   - public.ts (package public API)
+ *
+ * Add new types freely. Modify existing types only with a grep for all
+ * import sites in `packages/web/src/server/`.
+ *
+ * Rules:
+ * - Types only — no runtime code, no side effects.
+ * - Both zones import FROM here; neither zone re-exports these types.
+ * - New cross-zone types should be added here rather than in leaf files.
+ *
+ * @public
+ * @module web/server/shared-types
+ */
+export {};
+//# sourceMappingURL=shared-types.js.map

package/dist/server/shared-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared-types.js","sourceRoot":"","sources":["../../src/server/shared-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG"}

package/dist/server/start.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Server entry point — creates the HTTP server and wires up all routes.
+ */
+import { type FSWatcher } from "node:fs";
+import type { ViewerScope } from "./types.js";
+/**
+ * File written by the server process to communicate the actual port it bound to.
+ * Used by the orchestrator (web.js) to discover the port in background mode,
+ * where the server's stdout is not available.
+ */
+export declare const PORT_FILE = ".n-dx-web.port";
+/** Maximum time in milliseconds for the full graceful-shutdown sequence. */
+export declare const DEFAULT_SHUTDOWN_TIMEOUT_MS = 30000;
+/** @internal Injection points used in tests instead of global process calls. */
+export interface ShutdownDeps {
+    /** Replaces `process.exit()` so tests can verify exit codes without dying. */
+    exit?(code: number): void;
+}
+/**
+ * Registers SIGINT / SIGTERM signal handlers that co-ordinate a graceful
+ * shutdown of all dashboard components in dependency order:
+ *
+ *   1. Hench child processes  (highest priority: avoids orphaned agents)
+ *   2. WebSocket connections  (clients receive a clean close frame)
+ *   3. HTTP server            (stops accepting; drains in-flight requests)
+ *   4. Port file              (orchestrator sees the port as free)
+ *
+ * **Double-signal handling** — a second SIGINT/SIGTERM received while the
+ * graceful sequence is still running triggers an immediate `exit(1)`, so an
+ * operator can always escape a stuck shutdown with a second Ctrl-C.
+ *
+ * **Timeout** — if the full sequence exceeds `timeoutMs` the process is
+ * force-killed via `exit(1)` to prevent indefinite hangs.
+ *
+ * @param server       The HTTP server to drain and close.
+ * @param ws           WebSocket manager whose connections should be torn down.
+ * @param portFilePath Port file path to remove so the orchestrator sees the port as free.
+ * @param actualPort   Bound port number (for log messages only).
+ * @param timeoutMs    Max ms to wait before forcing exit (default 30 s, override
+ *                     via `N_DX_SHUTDOWN_TIMEOUT_MS` env var).
+ * @param deps         Injection points for unit testing (do not use in production).
+ */
+export declare function registerShutdownHandlers(server: {
+    close(cb: (err?: Error) => void): void;
+}, ws: {
+    shutdown(): void;
+}, portFilePath: string, actualPort: number, timeoutMs?: number, deps?: ShutdownDeps, watcherHandles?: WatcherHandles): void;
+/** Result returned by startServer with the actual port used. */
+export interface StartResult {
+    /** The actual port the server is listening on. */
+    port: number;
+    /** Whether a fallback port was used (requested port was unavailable). */
+    isFallback: boolean;
+}
+export interface ServerOptions {
+    dev?: boolean;
+    /** Restrict dashboard to a single package's views and APIs. */
+    scope?: ViewerScope;
+}
+/** Collected file system watchers and monitor intervals for cleanup during shutdown. */
+interface WatcherHandles {
+    watchers: FSWatcher[];
+    henchRunsDir: string;
+    /** Monitor intervals to clear on shutdown. */
+    monitorIntervals: ReturnType<typeof setInterval>[];
+}
+export declare function startServer(targetDir: string, port?: number, opts?: ServerOptions): Promise<StartResult>;
+export {};