@poolzin/pool-bot 2026.1.29 → 2026.1.31

package/dist/gateway/hooks/progressive-disclosure-details.js

@@ -0,0 +1,237 @@
+/**
+ * Progressive Disclosure - Details Layer (Phase 4)
+ *
+ * Load full memory content on-demand
+ * Safe: Read-only, rate-limited, lazy loading
+ *
+ * Purpose:
+ * - Only load full content when user explicitly requests
+ * - Provides: Complete file content, line ranges, metadata
+ * - Called only for specific results (not all results)
+ */
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+// ============================================================================
+// Constants
+// ============================================================================
+const MEMORY_DIR = "/root/pool";
+const MAX_CONTENT_SIZE = 100_000; // 100KB max per detail
+const RATE_LIMIT_MS = 100; // Min 100ms between loads
+// ============================================================================
+// Rate Limiting (prevent abuse)
+// ============================================================================
+let lastLoadTime = 0;
+/**
+ * Rate limiter for detail loading
+ * Safe: Prevents excessive I/O operations
+ */
+async function rateLimit() {
+    const now = Date.now();
+    const elapsed = now - lastLoadTime;
+    if (elapsed < RATE_LIMIT_MS) {
+        const delay = RATE_LIMIT_MS - elapsed;
+        await new Promise((resolve) => setTimeout(resolve, delay));
+    }
+    lastLoadTime = Date.now();
+}
+// ============================================================================
+// Details Layer Implementation
+// ============================================================================
+/**
+ * Load full memory details for given result IDs
+ * Safe: Rate-limited, size-limited, handles errors gracefully
+ *
+ * @param ids - Result IDs (format: "memory/YYYY-MM-DD.md#L123")
+ * @returns Map of IDs to MemoryDetail
+ */
+export async function loadFullDetails(ids) {
+    // Validate inputs
+    if (!ids || ids.length === 0) {
+        return {};
+    }
+    try {
+        const details = {};
+        // Load each detail with rate limiting
+        for (const id of ids) {
+            await rateLimit();
+            const detail = await loadDetailForId(id);
+            if (detail) {
+                details[id] = detail;
+            }
+        }
+        return details;
+    }
+    catch (err) {
+        console.error("[pd-details] Failed to load details:", err);
+        return {};
+    }
+}
+/**
+ * Load detail for a single ID
+ * Safe: Returns null if invalid or error
+ */
+async function loadDetailForId(id) {
+    try {
+        // Parse ID to extract file path and line range
+        const { filePath, lineRange } = parseId(id);
+        // Read file content
+        const content = await readFile(filePath, "utf-8");
+        // Validate content size
+        if (content.length > MAX_CONTENT_SIZE) {
+            console.warn(`[pd-details] Content too large for ${id}, truncating`);
+            return createMemoryDetail(id, content.slice(0, MAX_CONTENT_SIZE), filePath, lineRange, true);
+        }
+        return createMemoryDetail(id, content, filePath, lineRange, false);
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
+            // File doesn't exist
+            return null;
+        }
+        // Other error
+        console.error(`[pd-details] Failed to load ${id}:`, err);
+        return null;
+    }
+}
+/**
+ * Parse result ID to extract file path and line range
+ * Safe: Returns defaults if invalid format
+ */
+function parseId(id) {
+    try {
+        // Format: "memory/YYYY-MM-DD.md#L123" or "MEMORY.md#L10-20"
+        const match = id.match(/^(.+\.md)(?:#L(\d+)(?:-(\d+))?)?$/);
+        if (!match) {
+            throw new Error(`Invalid ID format: ${id}`);
+        }
+        const [, fileName, startLine, endLine] = match;
+        // Determine file path
+        let filePath;
+        if (fileName === "MEMORY.md") {
+            filePath = join(MEMORY_DIR, "MEMORY.md");
+        }
+        else {
+            filePath = join(MEMORY_DIR, fileName);
+        }
+        // Parse line range
+        const lineRange = startLine
+            ? {
+                start: parseInt(startLine, 10),
+                end: endLine ? parseInt(endLine, 10) : parseInt(startLine, 10),
+            }
+            : undefined;
+        return { filePath, lineRange };
+    }
+    catch (err) {
+        // Invalid format, return defaults
+        console.warn(`[pd-details] Invalid ID format: ${id}`);
+        return { filePath: join(MEMORY_DIR, "MEMORY.md") };
+    }
+}
+/**
+ * Create MemoryDetail object
+ */
+function createMemoryDetail(id, content, filePath, lineRange, truncated) {
+    return {
+        id,
+        content,
+        compressed: truncated,
+        lines: lineRange,
+        metadata: {
+            fileType: filePath.includes("MEMORY.md") && !filePath.includes("memory/") ? "MEMORY" : "DAILY",
+            size: content.length,
+            lastModified: Date.now(), // Approximate (would need fs.stat for real)
+        },
+    };
+}
+// ============================================================================
+// Batch Loading (with concurrency limit)
+// ============================================================================
+/**
+ * Load details in batches (limited concurrency)
+ * Safe: Prevents overwhelming the file system
+ *
+ * @param ids - Result IDs to load
+ * @param batchSize - Max concurrent loads (default: 5)
+ * @returns Map of IDs to MemoryDetail
+ */
+export async function loadDetailsBatch(ids, batchSize = 5) {
+    const details = {};
+    // Process in batches
+    for (let i = 0; i < ids.length; i += batchSize) {
+        const batch = ids.slice(i, i + batchSize);
+        // Load batch in parallel
+        const promises = batch.map(async (id) => {
+            await rateLimit();
+            return loadDetailForId(id);
+        });
+        const results = await Promise.allSettled(promises);
+        // Merge results
+        for (let j = 0; j < results.length; j++) {
+            const result = results[j];
+            const id = batch[j];
+            if (result.status === "fulfilled" && result.value) {
+                details[id] = result.value;
+            }
+        }
+    }
+    return details;
+}
+// ============================================================================
+// Content Extraction (for line ranges)
+// ============================================================================
+/**
+ * Extract specific lines from content
+ * Safe: Handles out-of-range gracefully
+ *
+ * @param content - Full file content
+ * @param startLine - Start line number (1-indexed)
+ * @param endLine - End line number (1-indexed)
+ * @returns Extracted lines
+ */
+export function extractLines(content, startLine, endLine) {
+    const lines = content.split("\n");
+    // Adjust to 0-indexed
+    const start = Math.max(0, startLine - 1);
+    const end = Math.min(lines.length, endLine);
+    return lines.slice(start, end).join("\n");
+}
+// ============================================================================
+// Utilities (for testing)
+// ============================================================================
+/**
+ * Get file stats (size, last modified)
+ * Safe: Returns defaults if error
+ */
+async function getFileStats(filePath) {
+    try {
+        const { stat } = await import("node:fs/promises");
+        const stats = await stat(filePath);
+        return {
+            size: stats.size,
+            lastModified: stats.mtimeMs,
+        };
+    }
+    catch {
+        // Fallback to approximate values
+        return {
+            size: 0,
+            lastModified: Date.now(),
+        };
+    }
+}
+/**
+ * Reset rate limiter (for testing)
+ */
+export function resetRateLimiter() {
+    lastLoadTime = 0;
+}
+/**
+ * Get rate limiter stats (for testing)
+ */
+export function getRateLimiterStats() {
+    return {
+        lastLoadTime,
+        rateLimit: RATE_LIMIT_MS,
+    };
+}

package/dist/gateway/hooks/progressive-disclosure-index.js

@@ -0,0 +1,354 @@
+/**
+ * Progressive Disclosure - Index Layer (Phase 2)
+ *
+ * Lightweight search: returns only index + snippets
+ * Token savings: ~90% vs full content search
+ *
+ * Safe:
+ * - Read-only operations (no modifications)
+ * - Pure functions (no side effects)
+ * - Cacheable results
+ */
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { PROGRESSIVE_DISCLOSURE_FLAGS } from "./progressive-disclosure-types.js";
+// ============================================================================
+// Constants
+// ============================================================================
+const MEMORY_DIR = "/root/pool";
+const MAX_SNIPPET_LENGTH = 100;
+const DEFAULT_MAX_RESULTS = 10;
+const MIN_SCORE_THRESHOLD = 0.1;
+// ============================================================================
+// Cache Implementation (in-memory, thread-safe for single-threaded Node.js)
+// ============================================================================
+const cache = new Map();
+/**
+ * Generate cache key from query
+ */
+function getCacheKey(query, options) {
+    const filter = options.tags?.join(",") || "";
+    const range = options.dateRange ? `${options.dateRange.start}-${options.dateRange.end}` : "";
+    return `${query}:${filter}:${range}:${options.maxResults || DEFAULT_MAX_RESULTS}`;
+}
+/**
+ * Get from cache if valid
+ */
+function getFromCache(key) {
+    if (!PROGRESSIVE_DISCLOSURE_FLAGS.CACHE_ENABLED) {
+        return null;
+    }
+    const cached = cache.get(key);
+    if (!cached) {
+        return null;
+    }
+    // Check TTL
+    const age = Date.now() - cached.timestamp;
+    if (age > PROGRESSIVE_DISCLOSURE_FLAGS.CACHE_TTL_MS) {
+        cache.delete(key);
+        return null;
+    }
+    if (PROGRESSIVE_DISCLOSURE_FLAGS.DEBUG_MODE) {
+        console.log(`[pd-index] Cache hit: ${key}`);
+    }
+    return cached.results;
+}
+/**
+ * Save to cache (respecting max size)
+ */
+function saveToCache(key, results) {
+    if (!PROGRESSIVE_DISCLOSURE_FLAGS.CACHE_ENABLED) {
+        return;
+    }
+    // Enforce max cache size
+    if (cache.size >= PROGRESSIVE_DISCLOSURE_FLAGS.CACHE_MAX_SIZE) {
+        // Remove oldest entry (first key in map)
+        const firstKey = cache.keys().next().value;
+        if (firstKey) {
+            cache.delete(firstKey);
+        }
+    }
+    cache.set(key, {
+        key,
+        results,
+        timestamp: Date.now(),
+        ttl: PROGRESSIVE_DISCLOSURE_FLAGS.CACHE_TTL_MS,
+    });
+    if (PROGRESSIVE_DISCLOSURE_FLAGS.DEBUG_MODE) {
+        console.log(`[pd-index] Cached: ${key} (${results.length} results)`);
+    }
+}
+/**
+ * Clear all cache (for testing)
+ */
+export function clearIndexCache() {
+    cache.clear();
+}
+/**
+ * Get cache statistics
+ */
+export function getIndexCacheStats() {
+    return {
+        size: cache.size,
+        maxSize: PROGRESSIVE_DISCLOSURE_FLAGS.CACHE_MAX_SIZE,
+        ttl: PROGRESSIVE_DISCLOSURE_FLAGS.CACHE_TTL_MS,
+        enabled: PROGRESSIVE_DISCLOSURE_FLAGS.CACHE_ENABLED,
+    };
+}
+// ============================================================================
+// Index Layer Implementation
+// ============================================================================
+/**
+ * Search memory files and return lightweight index
+ * Safe: Read-only, cacheable, pure function
+ *
+ * @param query - Search query string
+ * @param options - Search options
+ * @returns Array of search results (lightweight)
+ */
+export async function searchIndexOnly(query, options = {}) {
+    // Validate inputs
+    const safeQuery = query?.trim() || "";
+    if (!safeQuery) {
+        return [];
+    }
+    const maxResults = options.maxResults || DEFAULT_MAX_RESULTS;
+    const threshold = options.threshold ?? MIN_SCORE_THRESHOLD;
+    // Check cache
+    const cacheKey = getCacheKey(safeQuery, options);
+    const cached = getFromCache(cacheKey);
+    if (cached) {
+        return cached.slice(0, maxResults);
+    }
+    try {
+        // Search in memory files
+        const results = await searchMemoryFiles(safeQuery, options);
+        // Filter by threshold
+        const filtered = results.filter((r) => r.score >= threshold);
+        // Sort by score (descending)
+        const sorted = filtered.sort((a, b) => b.score - a.score);
+        // Limit results
+        const limited = sorted.slice(0, maxResults);
+        // Cache results
+        saveToCache(cacheKey, limited);
+        return limited;
+    }
+    catch (err) {
+        console.error("[pd-index] Search failed:", err);
+        return [];
+    }
+}
+/**
+ * Search memory files (main implementation)
+ * Safe: Read-only, handles errors gracefully
+ */
+async function searchMemoryFiles(query, options) {
+    const results = [];
+    const queryLower = query.toLowerCase();
+    // Files to search (in order of priority)
+    const filesToSearch = getFilesToSearch(options);
+    for (const filePath of filesToSearch) {
+        try {
+            const content = await readFile(filePath, "utf-8");
+            const lines = content.split("\n");
+            // Extract date from filename
+            const date = extractDate(filePath);
+            // Search for matches
+            const matches = findMatchesInContent(content, lines, queryLower, filePath, date);
+            results.push(...matches);
+        }
+        catch (err) {
+            // Skip files that can't be read
+            if (PROGRESSIVE_DISCLOSURE_FLAGS.DEBUG_MODE) {
+                console.warn(`[pd-index] Failed to read ${filePath}:`, err);
+            }
+        }
+    }
+    return results;
+}
+/**
+ * Get list of files to search based on options
+ */
+function getFilesToSearch(options) {
+    const files = [];
+    // Always search MEMORY.md first
+    files.push(join(MEMORY_DIR, "MEMORY.md"));
+    // Search daily memory files
+    if (!options.dateRange) {
+        // No date filter: search all daily files
+        // For now, just search recent files (last 30 days)
+        const recentFiles = getRecentDailyFiles(30);
+        files.push(...recentFiles);
+    }
+    else {
+        // Date range filter
+        const rangeFiles = getDailyFilesInRange(options.dateRange.start, options.dateRange.end);
+        files.push(...rangeFiles);
+    }
+    return files;
+}
+/**
+ * Get recent daily memory files
+ * Safe: Returns empty array if directory doesn't exist
+ */
+function getRecentDailyFiles(days) {
+    const files = [];
+    const now = new Date();
+    for (let i = 0; i < days; i++) {
+        const date = new Date(now);
+        date.setDate(date.getDate() - i);
+        const dateStr = date.toISOString().split("T")[0];
+        const filePath = join(MEMORY_DIR, "memory", `${dateStr}.md`);
+        files.push(filePath);
+    }
+    return files;
+}
+/**
+ * Get daily files in date range
+ */
+function getDailyFilesInRange(start, end) {
+    const files = [];
+    const startDate = new Date(start);
+    const endDate = new Date(end);
+    const currentDate = new Date(startDate);
+    while (currentDate <= endDate) {
+        const dateStr = currentDate.toISOString().split("T")[0];
+        const filePath = join(MEMORY_DIR, "memory", `${dateStr}.md`);
+        files.push(filePath);
+        // Next day
+        currentDate.setDate(currentDate.getDate() + 1);
+    }
+    return files;
+}
+/**
+ * Extract date from file path
+ */
+function extractDate(filePath) {
+    // Format: /root/pool/memory/2026-02-04.md -> 2026-02-04
+    const match = filePath.match(/(\d{4}-\d{2}-\d{2})\.md$/);
+    if (match) {
+        return match[1];
+    }
+    // MEMORY.md -> today's date
+    return new Date().toISOString().split("T")[0];
+}
+/**
+ * Find matches in content (simple string matching)
+ * Safe: No regex, handles edge cases
+ */
+function findMatchesInContent(content, lines, queryLower, filePath, date) {
+    const results = [];
+    const queryWords = queryLower.split(/\s+/);
+    // Scan content for matches
+    let matchCount = 0;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const lineLower = line.toLowerCase();
+        // Simple word matching (all query words must be present)
+        const allWordsPresent = queryWords.every((word) => lineLower.includes(word));
+        if (!allWordsPresent) {
+            continue;
+        }
+        // Calculate score (simple: word count / line length)
+        const score = calculateScore(line, queryWords);
+        // Create result
+        const result = {
+            id: `${filePath}#L${i + 1}`,
+            date,
+            snippet: extractSnippet(line, content, i),
+            score,
+            tags: extractTags(line, content),
+            title: extractTitle(content),
+        };
+        results.push(result);
+        matchCount++;
+        // Limit matches per file (avoid too many from same file)
+        if (matchCount >= 5) {
+            break;
+        }
+    }
+    return results;
+}
+/**
+ * Calculate relevance score
+ * Simple heuristic: more query words = higher score
+ */
+function calculateScore(line, queryWords) {
+    const lineLower = line.toLowerCase();
+    let matchCount = 0;
+    for (const word of queryWords) {
+        if (lineLower.includes(word)) {
+            matchCount++;
+        }
+    }
+    // Score = (matches / total words) normalized 0-1
+    const baseScore = matchCount / queryWords.length;
+    // Boost score for shorter lines (more focused)
+    const lengthBonus = Math.max(0, 1 - line.length / 500);
+    return Math.min(1, baseScore * 0.8 + lengthBonus * 0.2);
+}
+/**
+ * Extract snippet (preview)
+ */
+function extractSnippet(line, content, lineIndex) {
+    // Return first MAX_SNIPPET_LENGTH chars of line
+    if (line.length <= MAX_SNIPPET_LENGTH) {
+        return line;
+    }
+    return line.slice(0, MAX_SNIPPET_LENGTH) + "...";
+}
+/**
+ * Extract tags from content (simple heuristic)
+ */
+function extractTags(line, content) {
+    const tags = [];
+    const lineLower = line.toLowerCase();
+    // Simple tag detection based on keywords
+    const tagKeywords = [
+        "decision",
+        "project",
+        "todo",
+        "important",
+        "bug",
+        "feature",
+        "fix",
+        "deploy",
+        "meeting",
+        "review",
+    ];
+    for (const keyword of tagKeywords) {
+        if (lineLower.includes(keyword)) {
+            tags.push(keyword);
+        }
+    }
+    return tags;
+}
+/**
+ * Extract title from content (first heading)
+ */
+function extractTitle(content) {
+    const match = content.match(/^#\s+(.+)$/m);
+    return match ? match[1].trim() : undefined;
+}
+// ============================================================================
+// Public API (for testing)
+// ============================================================================
+/**
+ * Force cache invalidation (for testing)
+ */
+export function invalidateIndexCache(query) {
+    if (query) {
+        // Invalidate all cache keys containing the query
+        const keysToDelete = [];
+        cache.forEach((_, key) => {
+            if (key.startsWith(query)) {
+                keysToDelete.push(key);
+            }
+        });
+        keysToDelete.forEach((key) => cache.delete(key));
+    }
+    else {
+        // Clear all cache
+        cache.clear();
+    }
+}