sidekick-shared 0.27.6 → 0.28.0

package/dist/esm/search/advancedFilter.js

@@ -0,0 +1,197 @@
+/**
+ * Multi-mode filter engine for session events.
+ *
+ * Supports 4 filter modes: substring, fuzzy, regex, and date range.
+ * Provides both filtering and match highlighting for CLI (blessed) and VS Code (HTML).
+ *
+ * @module search/advancedFilter
+ */
+export class FilterEngine {
+    mode = 'substring';
+    query = '';
+    since;
+    until;
+    // Cached compiled regex
+    compiledRegex = null;
+    regexError = null;
+    // Cached fuzzy words
+    fuzzyWords = [];
+    /** Set the active filter mode. */
+    setMode(mode) {
+        this.mode = mode;
+        this.recompile();
+    }
+    /** Set the query string (used by substring, fuzzy, regex modes). */
+    setQuery(text) {
+        this.query = text;
+        this.recompile();
+    }
+    /** Set date range bounds (used by date mode). */
+    setDateRange(since, until) {
+        this.since = since;
+        this.until = until;
+    }
+    /** Get the current filter state. */
+    getState() {
+        return { mode: this.mode, query: this.query, since: this.since, until: this.until };
+    }
+    /** Whether the current regex is valid (always true for non-regex modes). */
+    get isValid() {
+        if (this.mode !== 'regex')
+            return true;
+        return this.regexError === null;
+    }
+    /** Regex compilation error, or null if valid. */
+    get error() {
+        return this.mode === 'regex' ? this.regexError : null;
+    }
+    /** Whether the filter has an active query. */
+    get isActive() {
+        if (this.mode === 'date')
+            return !!(this.since || this.until);
+        return this.query.length > 0;
+    }
+    /** Test whether a FollowEvent matches the current filter. */
+    matches(event) {
+        if (!this.isActive)
+            return true;
+        switch (this.mode) {
+            case 'substring':
+                return this.matchSubstring(event.summary);
+            case 'fuzzy':
+                return this.matchFuzzy(event.summary);
+            case 'regex':
+                return this.matchRegex(event.summary);
+            case 'date':
+                return this.matchDate(event.timestamp);
+            default:
+                return true;
+        }
+    }
+    /** Test whether arbitrary text matches the current filter (for PanelItem labels etc). */
+    matchesText(text) {
+        if (!this.isActive)
+            return true;
+        switch (this.mode) {
+            case 'substring':
+                return this.matchSubstring(text);
+            case 'fuzzy':
+                return this.matchFuzzy(text);
+            case 'regex':
+                return this.matchRegex(text);
+            case 'date':
+                return true; // date mode doesn't filter text
+            default:
+                return true;
+        }
+    }
+    /**
+     * Highlight matched portions of text in the given format.
+     * Returns the text with matched substrings wrapped in highlight tags.
+     */
+    highlightMatches(text, format) {
+        if (!this.isActive || !text)
+            return text;
+        switch (this.mode) {
+            case 'substring':
+                return this.highlightSubstring(text, format);
+            case 'fuzzy':
+                return this.highlightFuzzy(text, format);
+            case 'regex':
+                return this.highlightRegex(text, format);
+            case 'date':
+                return text; // no highlighting for date mode
+            default:
+                return text;
+        }
+    }
+    // ── Private: matching ──
+    matchSubstring(text) {
+        return text.includes(this.query);
+    }
+    matchFuzzy(text) {
+        const lower = text.toLowerCase();
+        return this.fuzzyWords.every((w) => lower.includes(w));
+    }
+    matchRegex(text) {
+        if (!this.compiledRegex)
+            return false;
+        this.compiledRegex.lastIndex = 0;
+        return this.compiledRegex.test(text);
+    }
+    matchDate(timestamp) {
+        if (this.since && timestamp < this.since)
+            return false;
+        if (this.until && timestamp > this.until)
+            return false;
+        return true;
+    }
+    // ── Private: highlighting ──
+    highlightSubstring(text, format) {
+        if (!this.query)
+            return text;
+        return this.wrapMatches(text, this.escapeRegex(this.query), format);
+    }
+    highlightFuzzy(text, format) {
+        if (this.fuzzyWords.length === 0)
+            return text;
+        // Highlight each fuzzy word independently
+        const pattern = this.fuzzyWords.map((w) => this.escapeRegex(w)).join('|');
+        return this.wrapMatches(text, pattern, format, 'gi');
+    }
+    highlightRegex(text, format) {
+        if (!this.compiledRegex)
+            return text;
+        return this.wrapMatches(text, this.query, format, 'g');
+    }
+    wrapMatches(text, pattern, format, flags = 'g') {
+        let regex;
+        try {
+            regex = new RegExp(`(${pattern})`, flags);
+        }
+        catch {
+            return text;
+        }
+        const [open, close] = this.getHighlightTags(format);
+        return text.replace(regex, `${open}$1${close}`);
+    }
+    getHighlightTags(format) {
+        switch (format) {
+            case 'blessed':
+                return ['{blue-bg}{white-fg}', '{/white-fg}{/blue-bg}'];
+            case 'ansi':
+                return ['\x1b[0;44m', '\x1b[0m'];
+            case 'html':
+                return ['<mark class="sk-search-match">', '</mark>'];
+            default:
+                return ['', ''];
+        }
+    }
+    // ── Private: compilation ──
+    recompile() {
+        // Reset cached state
+        this.compiledRegex = null;
+        this.regexError = null;
+        this.fuzzyWords = [];
+        switch (this.mode) {
+            case 'regex':
+                try {
+                    this.compiledRegex = new RegExp(this.query, 'g');
+                    this.regexError = null;
+                }
+                catch (e) {
+                    this.regexError = e instanceof Error ? e.message : 'Invalid regex';
+                }
+                break;
+            case 'fuzzy':
+                this.fuzzyWords = this.query
+                    .toLowerCase()
+                    .split(/\s+/)
+                    .filter((w) => w.length > 0);
+                break;
+        }
+    }
+    escapeRegex(s) {
+        return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    }
+}

package/dist/esm/search/sessionSearch.js

@@ -0,0 +1,66 @@
+/** Provider-aware cross-session search. */
+import { resolveProjectIdentity } from '../paths';
+async function enumerateSessions(provider, options) {
+    const workspace = options.projectPath
+        ? resolveProjectIdentity(options.projectPath).resolvedCwd
+        : undefined;
+    if (!options.projectSlug || workspace) {
+        if (provider.listSessionFilesAsync)
+            return provider.listSessionFilesAsync(workspace);
+        if (workspace) {
+            return provider
+                .findAllSessions(workspace)
+                .map((path) => ({ path, mtime: new Date(0), workspacePath: workspace }));
+        }
+        if (provider.listAllSessionFiles)
+            return provider.listAllSessionFiles();
+    }
+    // Older/custom providers can expose virtual project directories. Let the
+    // provider enumerate them instead of assuming a particular on-disk layout.
+    const files = [];
+    for (const folder of provider.getAllProjectFolders()) {
+        if (options.signal?.aborted)
+            break;
+        if (options.projectSlug && folder.encodedName !== options.projectSlug)
+            continue;
+        const paths = provider.id === 'codex'
+            ? provider.findAllSessions(folder.name)
+            : provider.findSessionsInDirectory(folder.dir);
+        files.push(...paths.map((path) => ({ path, mtime: folder.lastModified, workspacePath: folder.name })));
+    }
+    return files;
+}
+export async function searchSessions(provider, query, options = {}) {
+    const maxResults = options.maxResults ?? 50;
+    const results = [];
+    if (maxResults <= 0 || !query.trim() || options.signal?.aborted)
+        return results;
+    const files = await enumerateSessions(provider, options);
+    const seen = new Set();
+    files.sort((a, b) => b.mtime.getTime() - a.mtime.getTime());
+    for (const file of files) {
+        if (results.length >= maxResults || options.signal?.aborted)
+            break;
+        if (seen.has(file.path))
+            continue;
+        seen.add(file.path);
+        try {
+            const hits = provider.searchInSession(file.path, query, maxResults - results.length);
+            for (const hit of hits.slice(0, maxResults - results.length)) {
+                results.push({
+                    providerId: provider.id,
+                    projectPath: hit.projectPath || file.workspacePath || '',
+                    sessionPath: hit.sessionPath,
+                    snippet: hit.line,
+                    eventType: hit.eventType,
+                    timestamp: hit.timestamp,
+                });
+            }
+        }
+        catch {
+            // An unreadable session must not hide matches in the remaining sessions.
+        }
+        await new Promise((resolve) => setImmediate(resolve));
+    }
+    return results;
+}

package/dist/esm/sessionFingerprint.js

@@ -0,0 +1,40 @@
+/**
+ * Size/mtime fingerprints for session sources.
+ *
+ * Shared by the observed-session collector, the V1 adapter's watch loop, and
+ * the usage cache, so "has this session changed?" is answered the same way
+ * everywhere without re-reading content.
+ *
+ * @module sessionFingerprint
+ */
+import { statSync } from 'node:fs';
+/** Structured size/mtime fingerprint; returns null for inaccessible or synthetic paths. */
+export function fileFingerprintParts(sourcePath) {
+    try {
+        const stat = statSync(sourcePath);
+        return { sizeBytes: stat.size, mtimeMs: stat.mtimeMs };
+    }
+    catch {
+        return null;
+    }
+}
+/** Size/mtime fingerprint suitable for retry bypass; returns null for synthetic DB locators. */
+export function fileFingerprint(sourcePath) {
+    const parts = fileFingerprintParts(sourcePath);
+    return parts ? fingerprintString(parts) : null;
+}
+/** Canonical `${sizeBytes}:${mtimeMs}` form of a fingerprint. */
+export function fingerprintString(parts) {
+    return `${parts.sizeBytes}:${parts.mtimeMs}`;
+}
+/**
+ * Fingerprint for a session path, falling back to provider metadata (mtime
+ * only) for database-backed sessions whose path is synthetic.
+ */
+export function sessionFingerprintParts(provider, sessionPath) {
+    const parts = fileFingerprintParts(sessionPath);
+    if (parts)
+        return parts;
+    const metadata = provider.getSessionMetadata?.(sessionPath);
+    return metadata ? { sizeBytes: 0, mtimeMs: metadata.mtime.getTime() } : null;
+}

package/dist/esm/sessionMonitor.js

@@ -0,0 +1,198 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { EventAggregator } from './aggregation/EventAggregator';
+import { ObservedSessionCollector, fileFingerprintParts } from './observedSessionCollector';
+/**
+ * UI-independent session monitor for library consumers. It owns one provider
+ * reader and the canonical aggregator; hosts decide how often to call `poll()`.
+ */
+export class SessionMonitor {
+    provider;
+    aggregator;
+    reader = null;
+    sessionPath = null;
+    listeners = new Set();
+    subscriptions = new Set();
+    replayOnAttach;
+    constructor(provider, options = {}) {
+        this.provider = provider;
+        this.replayOnAttach = options.replayOnAttach ?? true;
+        this.aggregator = new EventAggregator({ ...options, providerId: provider.id });
+    }
+    attach(sessionPath, replay = this.replayOnAttach) {
+        this.aggregator.reset();
+        this.reader = this.provider.createReader(sessionPath);
+        this.sessionPath = sessionPath;
+        if (replay)
+            this.consume(this.reader.readAll());
+        return this.getMetrics();
+    }
+    attachLatest(workspacePath, replay = this.replayOnAttach) {
+        const sessionPath = this.provider.findActiveSession(workspacePath);
+        return sessionPath ? this.attach(sessionPath, replay) : null;
+    }
+    poll() {
+        if (!this.reader)
+            return [];
+        if (this.reader.wasTruncated())
+            this.aggregator.reset();
+        const events = this.reader.readNew();
+        this.consume(events);
+        return events;
+    }
+    process(event) {
+        this.aggregator.processEvent(event);
+        for (const listener of this.listeners)
+            listener(event);
+    }
+    onEvent(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    /**
+     * Watches the attached session with debouncing and catch-up polling. Matching
+     * fingerprint changes automatically call poll(); parsed events still flow
+     * through onEvent.
+     */
+    subscribe(options = {}) {
+        const source = {
+            providerId: this.provider.id,
+            discover: async () => {
+                if (!this.sessionPath)
+                    return [];
+                let parts = fileFingerprintParts(this.sessionPath);
+                if (!parts) {
+                    try {
+                        const metadata = this.provider.getSessionMetadataAsync
+                            ? await this.provider.getSessionMetadataAsync(this.sessionPath)
+                            : this.provider.getSessionMetadata?.(this.sessionPath);
+                        parts = metadata ? { sizeBytes: 0, mtimeMs: metadata.mtime.getTime() } : null;
+                    }
+                    catch {
+                        parts = null;
+                    }
+                }
+                if (!parts)
+                    return [];
+                return [
+                    {
+                        sessionId: this.provider.getSessionId(this.sessionPath),
+                        sourceKey: this.sessionPath,
+                        fingerprintHint: `${parts.sizeBytes}:${parts.mtimeMs}`,
+                        fingerprintParts: parts,
+                    },
+                ];
+            },
+            read: () => null,
+            // One session is watched, so an event naming any other file costs
+            // nothing; an event naming this file costs one stat.
+            resolveReference: async (signal) => {
+                if (!signal.root || typeof signal.filename !== 'string' || !signal.filename) {
+                    return { status: 'unknown' };
+                }
+                if (!this.sessionPath)
+                    return { status: 'ignored' };
+                const eventPath = path.resolve(signal.root, signal.filename);
+                if (eventPath !== path.resolve(this.sessionPath))
+                    return { status: 'ignored' };
+                const [reference] = await source.discover();
+                return reference
+                    ? { status: 'present', reference }
+                    : { status: 'missing', sessionId: this.provider.getSessionId(this.sessionPath) };
+            },
+            subscribe: (listener, sourceOptions) => {
+                const watchers = new Set();
+                let pollTimer = null;
+                let roots;
+                try {
+                    roots = this.provider.getWatchRoots?.() ?? [this.provider.getProjectsBaseDir()];
+                }
+                catch {
+                    roots = [];
+                }
+                for (const root of new Set(roots)) {
+                    try {
+                        const watcher = fs.watch(root, { persistent: false, recursive: true }, (eventType, filename) => listener({
+                            trigger: 'event',
+                            root,
+                            eventType,
+                            filename: filename === null || filename === undefined ? null : String(filename),
+                        }));
+                        watchers.add(watcher);
+                        watcher.on('error', () => {
+                            watchers.delete(watcher);
+                            try {
+                                watcher.close();
+                            }
+                            catch {
+                                // Collector catch-up polling remains active.
+                            }
+                        });
+                    }
+                    catch {
+                        // Collector catch-up polling remains active.
+                    }
+                }
+                const pollIntervalMs = sourceOptions?.pollIntervalMs ?? 0;
+                if (pollIntervalMs > 0) {
+                    pollTimer = setInterval(() => listener({ trigger: 'poll' }), pollIntervalMs);
+                    pollTimer.unref?.();
+                }
+                return {
+                    dispose: () => {
+                        for (const watcher of watchers)
+                            watcher.close();
+                        watchers.clear();
+                        if (pollTimer)
+                            clearInterval(pollTimer);
+                    },
+                };
+            },
+        };
+        const collector = new ObservedSessionCollector({ sources: [source] });
+        const changeSubscription = collector.subscribe((batch) => {
+            if (batch.changes.some((change) => change.reference.sourceKey === this.sessionPath)) {
+                this.poll();
+            }
+            try {
+                options.onChange?.(batch);
+            }
+            catch {
+                // Change callbacks are observational.
+            }
+        }, {
+            debounceMs: options.debounceMs,
+            pollIntervalMs: options.pollIntervalMs,
+        });
+        const disposable = {
+            dispose: () => {
+                changeSubscription.dispose();
+                collector.dispose();
+                this.subscriptions.delete(disposable);
+            },
+        };
+        this.subscriptions.add(disposable);
+        return disposable;
+    }
+    getMetrics() {
+        return this.aggregator.getMetrics();
+    }
+    getSessionPath() {
+        return this.sessionPath;
+    }
+    reset() {
+        this.reader?.reset();
+        this.aggregator.reset();
+    }
+    dispose() {
+        for (const subscription of [...this.subscriptions])
+            subscription.dispose();
+        this.listeners.clear();
+        this.reader = null;
+        this.provider.dispose();
+    }
+    consume(events) {
+        for (const event of events)
+            this.process(event);
+    }
+}