stellar-memory 0.5.0

package/dist/scanner/index.js

@@ -0,0 +1,420 @@
+import { randomUUID } from 'node:crypto';
+import { resolve } from 'node:path';
+import { DEFAULT_SCAN_CONFIG } from './types.js';
+import { collectFilesWithStats, readTextFile, buildSourceHash, watchDirectory } from './local/filesystem.js';
+import { getParser } from './local/parsers/index.js';
+import { scanGitHistory } from './local/git.js';
+import { memoryExistsForSource, getMemoryBySourcePath, insertMemory, insertDataSource, updateDataSource, getAllDataSources, getDataSourceByPath, } from '../storage/queries.js';
+import { IMPACT_DEFAULTS } from '../engine/types.js';
+import { recencyScore, frequencyScore, importanceToDistance, } from '../engine/orbit.js';
+import { getConfig } from '../utils/config.js';
+// Full-scan exclude patterns (home directory scan)
+export const FULL_SCAN_EXTRA_EXCLUDES = [
+    'AppData', 'Application Data', '.npm', '.yarn', '.pnpm-store',
+    '.docker', '.gradle', '.m2', 'Temp', 'tmp', '.Trash', '.local',
+    'Library', 'Pictures', 'Videos', 'Music', 'Downloads', 'Desktop',
+    'OneDrive', '$Recycle.Bin', 'System Volume Information',
+    'ProgramData', 'Program Files', 'Program Files (x86)', 'Windows',
+];
+// ---------------------------------------------------------------------------
+// StellarScanner
+// ---------------------------------------------------------------------------
+export class StellarScanner {
+    config;
+    stopWatchers = [];
+    constructor(config = {}) {
+        this.config = {
+            ...DEFAULT_SCAN_CONFIG,
+            ...config,
+            // Merge array overrides rather than replacing defaults entirely
+            excludePatterns: config.excludePatterns ?? DEFAULT_SCAN_CONFIG.excludePatterns,
+            fileExtensions: config.fileExtensions ?? DEFAULT_SCAN_CONFIG.fileExtensions,
+        };
+    }
+    // -------------------------------------------------------------------------
+    // scan() — one-shot scan of all configured paths
+    // -------------------------------------------------------------------------
+    async scan() {
+        const startMs = Date.now();
+        let scannedFiles = 0;
+        let createdMemories = 0;
+        let skippedFiles = 0;
+        let errorFiles = 0;
+        const cfg = getConfig();
+        const project = cfg.defaultProject;
+        for (const scanPath of this.config.paths) {
+            const absPath = resolve(scanPath);
+            // Register or update data source record
+            await this._ensureDataSource(absPath);
+            // Collect files
+            const { entries, skippedCount } = await collectFilesWithStats(absPath, this.config);
+            skippedFiles += skippedCount;
+            // Process each file
+            for (const entry of entries) {
+                scannedFiles++;
+                const result = await this._processFile(entry, project);
+                if (result === 'created')
+                    createdMemories++;
+                else if (result === 'skip')
+                    skippedFiles++;
+                else
+                    errorFiles++;
+            }
+            // Update data source stats
+            const ds = getDataSourceByPath(absPath);
+            if (ds) {
+                updateDataSource(ds.id, {
+                    status: 'active',
+                    last_scanned_at: new Date().toISOString(),
+                    file_count: entries.length,
+                    total_size: entries.reduce((sum, e) => sum + e.size, 0),
+                });
+            }
+        }
+        // Git history scanning (if a configured path is a git repo)
+        for (const scanPath of this.config.paths) {
+            const absPath = resolve(scanPath);
+            createdMemories += this._insertGitMemories(absPath, project);
+        }
+        return {
+            scannedFiles,
+            createdMemories,
+            skippedFiles,
+            errorFiles,
+            durationMs: Date.now() - startMs,
+        };
+    }
+    // -------------------------------------------------------------------------
+    // scanPath() — scan a single directory path (used by MCP tool)
+    // -------------------------------------------------------------------------
+    async scanPath(dirPath, opts = {}) {
+        const absPath = resolve(dirPath);
+        const startMs = Date.now();
+        let scannedFiles = 0;
+        let createdMemories = 0;
+        let skippedFiles = 0;
+        let errorFiles = 0;
+        const cfg = getConfig();
+        const project = cfg.defaultProject;
+        await this._ensureDataSource(absPath);
+        const localConfig = { ...this.config };
+        if (opts.recursive === false) {
+            // Non-recursive: override with a sentinel — collectFiles checks for it
+            localConfig.paths = [absPath];
+        }
+        const { entries, skippedCount } = await collectFilesWithStats(absPath, localConfig);
+        skippedFiles += skippedCount;
+        for (const entry of entries) {
+            scannedFiles++;
+            const result = await this._processFile(entry, project);
+            if (result === 'created')
+                createdMemories++;
+            else if (result === 'skip')
+                skippedFiles++;
+            else
+                errorFiles++;
+        }
+        const ds = getDataSourceByPath(absPath);
+        if (ds) {
+            updateDataSource(ds.id, {
+                status: 'active',
+                last_scanned_at: new Date().toISOString(),
+                file_count: entries.length,
+                total_size: entries.reduce((sum, e) => sum + e.size, 0),
+            });
+        }
+        if (opts.includeGit !== false) {
+            createdMemories += this._insertGitMemories(absPath, project);
+        }
+        return {
+            scannedFiles,
+            createdMemories,
+            skippedFiles,
+            errorFiles,
+            durationMs: Date.now() - startMs,
+        };
+    }
+    // -------------------------------------------------------------------------
+    // scanWithProgress() — scan with progress callbacks + abort support
+    // -------------------------------------------------------------------------
+    async scanWithProgress(opts) {
+        const startMs = Date.now();
+        let scannedFiles = 0;
+        let createdMemories = 0;
+        let skippedFiles = 0;
+        let errorFiles = 0;
+        const cfg = getConfig();
+        const project = cfg.defaultProject;
+        const scanPaths = opts.paths && opts.paths.length > 0
+            ? opts.paths
+            : this.config.paths;
+        for (const scanPath of scanPaths) {
+            if (opts.abortSignal?.aborted)
+                break;
+            const absPath = resolve(scanPath);
+            opts.onProgress({ phase: 'collecting', path: absPath });
+            await this._ensureDataSource(absPath);
+            const { entries, skippedCount } = await collectFilesWithStats(absPath, this.config);
+            skippedFiles += skippedCount;
+            opts.onProgress({
+                phase: 'collected',
+                path: absPath,
+                totalFiles: entries.length,
+            });
+            for (const entry of entries) {
+                if (opts.abortSignal?.aborted)
+                    break;
+                scannedFiles++;
+                opts.onProgress({
+                    phase: 'processing',
+                    path: absPath,
+                    currentFile: entry.path,
+                    totalFiles: entries.length,
+                    scannedFiles,
+                    createdMemories,
+                    skippedFiles,
+                    errorFiles,
+                });
+                const result = await this._processFile(entry, project);
+                if (result === 'created')
+                    createdMemories++;
+                else if (result === 'skip')
+                    skippedFiles++;
+                else
+                    errorFiles++;
+            }
+            // Update data source stats
+            const ds = getDataSourceByPath(absPath);
+            if (ds) {
+                updateDataSource(ds.id, {
+                    status: 'active',
+                    last_scanned_at: new Date().toISOString(),
+                    file_count: entries.length,
+                    total_size: entries.reduce((sum, e) => sum + e.size, 0),
+                });
+            }
+            opts.onProgress({
+                phase: 'path_complete',
+                path: absPath,
+                scannedFiles,
+                createdMemories,
+                skippedFiles,
+                errorFiles,
+            });
+        }
+        // Git history scanning
+        if (opts.includeGit !== false && !opts.abortSignal?.aborted) {
+            for (const scanPath of scanPaths) {
+                if (opts.abortSignal?.aborted)
+                    break;
+                const absPath = resolve(scanPath);
+                createdMemories += this._insertGitMemories(absPath, project);
+            }
+        }
+        return {
+            scannedFiles,
+            createdMemories,
+            skippedFiles,
+            errorFiles,
+            durationMs: Date.now() - startMs,
+        };
+    }
+    // -------------------------------------------------------------------------
+    // watch() — start watching all configured paths for changes
+    // -------------------------------------------------------------------------
+    watch() {
+        const cfg = getConfig();
+        const project = cfg.defaultProject;
+        for (const scanPath of this.config.paths) {
+            const absPath = resolve(scanPath);
+            const stop = watchDirectory(absPath, this.config, async (_event, filePath) => {
+                const ext = filePath.slice(filePath.lastIndexOf('.')).toLowerCase();
+                const parser = getParser(ext);
+                if (!parser)
+                    return;
+                try {
+                    const stat = await import('node:fs/promises').then((m) => m.stat(filePath));
+                    const entry = {
+                        path: filePath,
+                        size: stat.size,
+                        mtimeMs: stat.mtimeMs,
+                        extension: ext,
+                    };
+                    await this._processFile(entry, project);
+                }
+                catch {
+                    // Ignore watcher errors
+                }
+            });
+            this.stopWatchers.push(stop);
+        }
+    }
+    // -------------------------------------------------------------------------
+    // stop() — stop all file watchers
+    // -------------------------------------------------------------------------
+    stop() {
+        for (const stop of this.stopWatchers)
+            stop();
+        this.stopWatchers = [];
+    }
+    // -------------------------------------------------------------------------
+    // Private: process one file entry
+    // -------------------------------------------------------------------------
+    async _processFile(entry, project) {
+        const parser = getParser(entry.extension);
+        if (!parser)
+            return 'skip';
+        const sourceHash = buildSourceHash(entry.path, entry.mtimeMs);
+        // Dedup check: same path + same mtime hash → skip
+        if (memoryExistsForSource(entry.path, sourceHash))
+            return 'skip';
+        // Check if there's an older memory for this path — soft-delete it so the
+        // FTS index stays tidy, then create a fresh one.
+        const existing = getMemoryBySourcePath(entry.path);
+        const content = await readTextFile(entry.path);
+        if (content === null)
+            return 'skip'; // binary or unreadable
+        let parsed;
+        try {
+            parsed = parser.parse(entry.path, content);
+        }
+        catch {
+            return 'error';
+        }
+        if (existing) {
+            // Reuse the existing memory's position / importance rather than starting fresh.
+            // We update the stored memory inline to avoid polluting the orbit log.
+            try {
+                const db = await import('../storage/database.js').then((m) => m.getDatabase());
+                const now = new Date().toISOString();
+                db.prepare(`
+          UPDATE memories
+          SET content = ?, summary = ?, tags = ?, metadata = ?,
+              source_hash = ?, updated_at = ?
+          WHERE id = ?
+        `).run(parsed.content, parsed.summary, JSON.stringify(parsed.tags), JSON.stringify({ ...parsed.metadata }), sourceHash, now, existing.id);
+                return 'created'; // "created" in the sense of "produced an up-to-date memory"
+            }
+            catch {
+                return 'error';
+            }
+        }
+        // Brand-new file — create a fresh memory planet using insertMemory directly
+        // so we can pass scanner-specific source fields (source, source_path, source_hash).
+        try {
+            const cfg = getConfig();
+            const type = parsed.type;
+            const impact = IMPACT_DEFAULTS[type] ?? 0.35;
+            const now = new Date().toISOString();
+            const rec = recencyScore(null, now, cfg.decayHalfLifeHours);
+            const freq = frequencyScore(0, cfg.frequencySaturationPoint);
+            const importance = Math.min(1.0, cfg.weights.recency * rec +
+                cfg.weights.frequency * freq +
+                cfg.weights.impact * impact +
+                cfg.weights.relevance * 0);
+            const distance = importanceToDistance(importance);
+            const raw = parsed.content.trim();
+            const summary = parsed.summary
+                ? parsed.summary
+                : raw.slice(0, 50).trimEnd() + (raw.length > 50 ? '\u2026' : '');
+            insertMemory({
+                id: randomUUID(),
+                project,
+                content: parsed.content,
+                summary,
+                type,
+                tags: parsed.tags,
+                distance,
+                importance,
+                velocity: 0,
+                impact,
+                access_count: 0,
+                last_accessed_at: null,
+                metadata: parsed.metadata,
+                source: 'scanner',
+                source_path: entry.path,
+                source_hash: sourceHash,
+                created_at: now,
+                updated_at: now,
+                deleted_at: null,
+            });
+            return 'created';
+        }
+        catch {
+            return 'error';
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Private: insert git commit memories using insertMemory directly
+    // -------------------------------------------------------------------------
+    _insertGitMemories(repoPath, project) {
+        const gitMemories = scanGitHistory(repoPath, 50);
+        const cfg = getConfig();
+        let count = 0;
+        for (const mem of gitMemories) {
+            try {
+                const type = mem.type;
+                const impact = IMPACT_DEFAULTS[type] ?? 0.5;
+                const now = new Date().toISOString();
+                const rec = recencyScore(null, now, cfg.decayHalfLifeHours);
+                const freq = frequencyScore(0, cfg.frequencySaturationPoint);
+                const importance = Math.min(1.0, cfg.weights.recency * rec +
+                    cfg.weights.frequency * freq +
+                    cfg.weights.impact * impact +
+                    cfg.weights.relevance * 0);
+                const distance = importanceToDistance(importance);
+                insertMemory({
+                    id: randomUUID(),
+                    project,
+                    content: mem.content,
+                    summary: mem.summary,
+                    type,
+                    tags: mem.tags,
+                    distance,
+                    importance,
+                    velocity: 0,
+                    impact,
+                    access_count: 0,
+                    last_accessed_at: null,
+                    metadata: mem.metadata,
+                    source: 'git',
+                    source_path: repoPath,
+                    source_hash: null,
+                    created_at: now,
+                    updated_at: now,
+                    deleted_at: null,
+                });
+                count++;
+            }
+            catch {
+                // Best-effort
+            }
+        }
+        return count;
+    }
+    // -------------------------------------------------------------------------
+    // Private: ensure a data_sources row exists for a path
+    // -------------------------------------------------------------------------
+    async _ensureDataSource(absPath) {
+        const existing = getDataSourceByPath(absPath);
+        if (existing)
+            return;
+        insertDataSource({
+            id: randomUUID(),
+            path: absPath,
+            type: 'local',
+            status: 'active',
+            last_scanned_at: null,
+            file_count: 0,
+            total_size: 0,
+            config: this.config,
+        });
+    }
+}
+// ---------------------------------------------------------------------------
+// Module-level convenience: list all registered sources
+// ---------------------------------------------------------------------------
+export function listDataSources() {
+    return getAllDataSources();
+}
+//# sourceMappingURL=index.js.map

package/dist/scanner/index.js.map

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

package/dist/scanner/local/filesystem.d.ts

@@ -0,0 +1,33 @@
+import type { FileEntry, ScanConfig } from '../types.js';
+/**
+ * Returns true if any segment of `filePath` matches any exclude pattern.
+ * Supports simple glob wildcards (* and ?) via a regex conversion.
+ */
+export declare function isExcluded(filePath: string, patterns: string[]): boolean;
+/**
+ * Build a deterministic dedup hash from the file path and mtime.
+ * We intentionally do NOT hash file content — that would be slow for large files.
+ * mtime changes whenever the file is modified, which is sufficient for our dedup.
+ */
+export declare function buildSourceHash(filePath: string, mtimeMs: number): string;
+/**
+ * Recursively collect all files under `dirPath` that pass config filters.
+ * Uses `opendir` (streaming, no giant readdir arrays) so it is memory-efficient.
+ */
+export declare function collectFiles(dirPath: string, config: ScanConfig, _depth?: number): Promise<FileEntry[]>;
+/** Read a file as UTF-8 text. Returns null on error (binary, permission, etc.). */
+export declare function readTextFile(filePath: string): Promise<string | null>;
+export type WatchCallback = (event: 'add' | 'change' | 'rename', filePath: string) => void;
+/**
+ * Watch `dirPath` recursively using Node's built-in `fs.watch`.
+ * Returns a cleanup function that stops watching when called.
+ */
+export declare function watchDirectory(dirPath: string, config: ScanConfig, callback: WatchCallback): () => void;
+/** Collect all files and also return the base name of skipped/binary files for reporting. */
+export declare function collectFilesWithStats(dirPath: string, config: ScanConfig): Promise<{
+    entries: FileEntry[];
+    skippedCount: number;
+}>;
+/** Return true if the filename looks like a typical dotfile to skip. */
+export declare function isDotfile(name: string): boolean;
+//# sourceMappingURL=filesystem.d.ts.map

package/dist/scanner/local/filesystem.js

@@ -0,0 +1,203 @@
+import { opendir, readFile, stat } from 'node:fs/promises';
+import { join, extname, basename } from 'node:path';
+import { createHash } from 'node:crypto';
+// ---------------------------------------------------------------------------
+// Exclude-pattern matching (no external deps)
+// ---------------------------------------------------------------------------
+/**
+ * Returns true if any segment of `filePath` matches any exclude pattern.
+ * Supports simple glob wildcards (* and ?) via a regex conversion.
+ */
+export function isExcluded(filePath, patterns) {
+    // Normalise to forward slashes for consistent matching
+    const normalised = filePath.replace(/\\/g, '/');
+    const segments = normalised.split('/');
+    for (const pattern of patterns) {
+        if (!pattern)
+            continue;
+        // Convert glob wildcard to regex
+        const reSource = pattern
+            .replace(/[.+^${}()|[\]\\]/g, '\\$&') // escape regex special chars (except * and ?)
+            .replace(/\*/g, '.*')
+            .replace(/\?/g, '.');
+        const re = new RegExp(`^${reSource}$`, 'i');
+        // Match against every path segment
+        if (segments.some((seg) => re.test(seg)))
+            return true;
+        // Also match against the whole normalised path
+        if (re.test(normalised))
+            return true;
+    }
+    return false;
+}
+// ---------------------------------------------------------------------------
+// Source hash
+// ---------------------------------------------------------------------------
+/**
+ * Build a deterministic dedup hash from the file path and mtime.
+ * We intentionally do NOT hash file content — that would be slow for large files.
+ * mtime changes whenever the file is modified, which is sufficient for our dedup.
+ */
+export function buildSourceHash(filePath, mtimeMs) {
+    return createHash('sha1')
+        .update(`${filePath}:${mtimeMs}`)
+        .digest('hex')
+        .slice(0, 16);
+}
+// ---------------------------------------------------------------------------
+// Recursive directory walker
+// ---------------------------------------------------------------------------
+/**
+ * Recursively collect all files under `dirPath` that pass config filters.
+ * Uses `opendir` (streaming, no giant readdir arrays) so it is memory-efficient.
+ */
+export async function collectFiles(dirPath, config, _depth = 0) {
+    const entries = [];
+    // Guard: never descend into excluded directories
+    if (isExcluded(dirPath, config.excludePatterns))
+        return entries;
+    let dir;
+    try {
+        dir = await opendir(dirPath);
+    }
+    catch {
+        // Permission denied or not a directory — skip silently
+        return entries;
+    }
+    const extSet = new Set(config.fileExtensions.map((e) => e.toLowerCase()));
+    for await (const dirent of dir) {
+        const fullPath = join(dirPath, dirent.name);
+        if (dirent.isDirectory()) {
+            if (!isExcluded(dirent.name, config.excludePatterns)) {
+                const sub = await collectFiles(fullPath, config, _depth + 1);
+                entries.push(...sub);
+            }
+            continue;
+        }
+        if (!dirent.isFile())
+            continue;
+        const ext = extname(dirent.name).toLowerCase();
+        if (!extSet.has(ext))
+            continue;
+        if (isExcluded(dirent.name, config.excludePatterns))
+            continue;
+        if (isExcluded(fullPath, config.excludePatterns))
+            continue;
+        // Stat to get size and mtime
+        let fileStat;
+        try {
+            fileStat = await stat(fullPath);
+        }
+        catch {
+            continue;
+        }
+        if (fileStat.size === 0 || fileStat.size > config.maxFileSize)
+            continue;
+        entries.push({
+            path: fullPath,
+            size: fileStat.size,
+            mtimeMs: fileStat.mtimeMs,
+            extension: ext,
+        });
+    }
+    return entries;
+}
+// ---------------------------------------------------------------------------
+// File content reader
+// ---------------------------------------------------------------------------
+/** Read a file as UTF-8 text. Returns null on error (binary, permission, etc.). */
+export async function readTextFile(filePath) {
+    try {
+        const buf = await readFile(filePath);
+        // Quick binary-detection heuristic: if the first 8 KB contains a null byte,
+        // treat it as binary and skip.
+        const sample = buf.slice(0, 8192);
+        for (let i = 0; i < sample.length; i++) {
+            if (sample[i] === 0)
+                return null;
+        }
+        return buf.toString('utf8');
+    }
+    catch {
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// File watcher (node:fs.watch wrapper)
+// ---------------------------------------------------------------------------
+import { watch as fsWatch } from 'node:fs';
+/**
+ * Watch `dirPath` recursively using Node's built-in `fs.watch`.
+ * Returns a cleanup function that stops watching when called.
+ */
+export function watchDirectory(dirPath, config, callback) {
+    const extSet = new Set(config.fileExtensions.map((e) => e.toLowerCase()));
+    const watcher = fsWatch(dirPath, { recursive: true }, (event, filename) => {
+        if (!filename)
+            return;
+        const fullPath = join(dirPath, filename);
+        const ext = extname(filename).toLowerCase();
+        if (!extSet.has(ext))
+            return;
+        if (isExcluded(fullPath, config.excludePatterns))
+            return;
+        const mapped = event === 'rename' ? 'rename' : 'change';
+        callback(mapped, fullPath);
+    });
+    return () => watcher.close();
+}
+/** Collect all files and also return the base name of skipped/binary files for reporting. */
+export async function collectFilesWithStats(dirPath, config) {
+    // We walk twice only to gather skip count — optimise by tracking inline
+    let skippedCount = 0;
+    async function walk(p) {
+        const result = [];
+        if (isExcluded(p, config.excludePatterns))
+            return result;
+        let dir;
+        try {
+            dir = await opendir(p);
+        }
+        catch {
+            return result;
+        }
+        const extSet = new Set(config.fileExtensions.map((e) => e.toLowerCase()));
+        for await (const dirent of dir) {
+            const fullPath = join(p, dirent.name);
+            if (dirent.isDirectory()) {
+                if (!isExcluded(dirent.name, config.excludePatterns)) {
+                    result.push(...(await walk(fullPath)));
+                }
+                continue;
+            }
+            if (!dirent.isFile())
+                continue;
+            const ext = extname(dirent.name).toLowerCase();
+            if (!extSet.has(ext) || isExcluded(dirent.name, config.excludePatterns) || isExcluded(fullPath, config.excludePatterns)) {
+                skippedCount++;
+                continue;
+            }
+            let fileStat;
+            try {
+                fileStat = await stat(fullPath);
+            }
+            catch {
+                skippedCount++;
+                continue;
+            }
+            if (fileStat.size === 0 || fileStat.size > config.maxFileSize) {
+                skippedCount++;
+                continue;
+            }
+            result.push({ path: fullPath, size: fileStat.size, mtimeMs: fileStat.mtimeMs, extension: ext });
+        }
+        return result;
+    }
+    const entries = await walk(dirPath);
+    return { entries, skippedCount };
+}
+/** Return true if the filename looks like a typical dotfile to skip. */
+export function isDotfile(name) {
+    return basename(name).startsWith('.');
+}
+//# sourceMappingURL=filesystem.js.map