@compilr-dev/agents 0.0.1

package/dist/memory/loader.d.ts

@@ -0,0 +1,114 @@
+/**
+ * ProjectMemoryLoader - Loads project-level instructions from markdown files
+ *
+ * Supports various LLM-specific naming conventions:
+ * - CLAUDE.md, .claude.md, .claude/instructions.md (Claude/Anthropic)
+ * - GEMINI.md, .gemini.md, .gemini/instructions.md (Google Gemini)
+ * - COPILOT.md, .github/copilot-instructions.md (GitHub Copilot)
+ * - GPT.md, OPENAI.md (OpenAI)
+ * - CURSOR.md, .cursor/rules (Cursor)
+ * - CODEIUM.md (Codeium)
+ *
+ * Also supports generic names:
+ * - PROJECT.md, INSTRUCTIONS.md, AI.md, CONTEXT.md
+ *
+ * @example
+ * ```typescript
+ * const loader = new ProjectMemoryLoader({
+ *   providers: ['claude', 'gemini'],
+ *   includeGeneric: true,
+ * });
+ *
+ * const memory = await loader.load('/path/to/project');
+ * console.log(memory.content); // Combined instructions
+ * ```
+ */
+import type { LLMProviderName, ProjectMemory, FilePattern, ProjectMemoryOptions, ProjectMemoryEventHandler, MemoryDiscoveryResult, ProviderPatterns } from './types.js';
+/**
+ * Built-in patterns for various LLM providers
+ */
+declare const PROVIDER_PATTERNS: ProviderPatterns[];
+/**
+ * Generic patterns that apply to any LLM
+ */
+declare const GENERIC_PATTERNS: FilePattern[];
+/**
+ * ProjectMemoryLoader discovers and loads project-specific instructions
+ */
+export declare class ProjectMemoryLoader {
+    private readonly options;
+    private readonly patterns;
+    private readonly eventHandlers;
+    constructor(options?: ProjectMemoryOptions);
+    /**
+     * Build the list of patterns to search for
+     */
+    private buildPatterns;
+    /**
+     * Load project memory from a directory
+     *
+     * @param rootDir - Starting directory for search
+     * @returns Loaded project memory
+     */
+    load(rootDir: string): Promise<ProjectMemory>;
+    /**
+     * Discover memory files without loading content
+     *
+     * @param rootDir - Starting directory for search
+     * @returns Discovery result with paths
+     */
+    discover(rootDir: string): Promise<MemoryDiscoveryResult>;
+    /**
+     * Get the list of directories to search
+     */
+    private getSearchDirectories;
+    /**
+     * Combine content from multiple files
+     */
+    private combineContent;
+    /**
+     * Format the header for a file
+     */
+    private formatHeader;
+    /**
+     * Register an event handler
+     */
+    onEvent(handler: ProjectMemoryEventHandler): () => void;
+    /**
+     * Emit an event
+     */
+    private emit;
+    /**
+     * Get the patterns being used
+     */
+    getPatterns(): FilePattern[];
+    /**
+     * Get the configured options
+     */
+    getOptions(): Required<ProjectMemoryOptions>;
+}
+/**
+ * Create a ProjectMemoryLoader with default options
+ */
+export declare function createProjectMemoryLoader(options?: ProjectMemoryOptions): ProjectMemoryLoader;
+/**
+ * Quick utility to load project memory
+ */
+export declare function loadProjectMemory(rootDir: string, options?: ProjectMemoryOptions): Promise<ProjectMemory>;
+/**
+ * Quick utility to check if a directory has project memory files
+ */
+export declare function hasProjectMemory(rootDir: string, options?: ProjectMemoryOptions): Promise<boolean>;
+/**
+ * Get built-in patterns for a provider
+ */
+export declare function getProviderPatterns(provider: LLMProviderName): FilePattern[];
+/**
+ * Get all supported provider names
+ */
+export declare function getSupportedProviders(): LLMProviderName[];
+/**
+ * Get generic patterns
+ */
+export declare function getGenericPatterns(): FilePattern[];
+export { PROVIDER_PATTERNS, GENERIC_PATTERNS };

package/dist/memory/loader.js

@@ -0,0 +1,463 @@
+/**
+ * ProjectMemoryLoader - Loads project-level instructions from markdown files
+ *
+ * Supports various LLM-specific naming conventions:
+ * - CLAUDE.md, .claude.md, .claude/instructions.md (Claude/Anthropic)
+ * - GEMINI.md, .gemini.md, .gemini/instructions.md (Google Gemini)
+ * - COPILOT.md, .github/copilot-instructions.md (GitHub Copilot)
+ * - GPT.md, OPENAI.md (OpenAI)
+ * - CURSOR.md, .cursor/rules (Cursor)
+ * - CODEIUM.md (Codeium)
+ *
+ * Also supports generic names:
+ * - PROJECT.md, INSTRUCTIONS.md, AI.md, CONTEXT.md
+ *
+ * @example
+ * ```typescript
+ * const loader = new ProjectMemoryLoader({
+ *   providers: ['claude', 'gemini'],
+ *   includeGeneric: true,
+ * });
+ *
+ * const memory = await loader.load('/path/to/project');
+ * console.log(memory.content); // Combined instructions
+ * ```
+ */
+import * as fs from 'fs/promises';
+import * as path from 'path';
+/**
+ * Built-in patterns for various LLM providers
+ */
+const PROVIDER_PATTERNS = [
+    {
+        provider: 'claude',
+        patterns: [
+            { pattern: 'CLAUDE.md', priority: 1, description: 'Claude project instructions' },
+            { pattern: '.claude.md', priority: 2, description: 'Hidden Claude instructions' },
+            {
+                pattern: '.claude/instructions.md',
+                priority: 3,
+                description: 'Claude directory instructions',
+            },
+            { pattern: '.claude/CLAUDE.md', priority: 4, description: 'Claude directory main file' },
+        ],
+    },
+    {
+        provider: 'anthropic',
+        patterns: [
+            { pattern: 'ANTHROPIC.md', priority: 1, description: 'Anthropic project instructions' },
+            { pattern: '.anthropic.md', priority: 2, description: 'Hidden Anthropic instructions' },
+            {
+                pattern: '.anthropic/instructions.md',
+                priority: 3,
+                description: 'Anthropic directory instructions',
+            },
+        ],
+    },
+    {
+        provider: 'gemini',
+        patterns: [
+            { pattern: 'GEMINI.md', priority: 1, description: 'Gemini project instructions' },
+            { pattern: '.gemini.md', priority: 2, description: 'Hidden Gemini instructions' },
+            {
+                pattern: '.gemini/instructions.md',
+                priority: 3,
+                description: 'Gemini directory instructions',
+            },
+        ],
+    },
+    {
+        provider: 'openai',
+        patterns: [
+            { pattern: 'OPENAI.md', priority: 1, description: 'OpenAI project instructions' },
+            { pattern: '.openai.md', priority: 2, description: 'Hidden OpenAI instructions' },
+            {
+                pattern: '.openai/instructions.md',
+                priority: 3,
+                description: 'OpenAI directory instructions',
+            },
+        ],
+    },
+    {
+        provider: 'gpt',
+        patterns: [
+            { pattern: 'GPT.md', priority: 1, description: 'GPT project instructions' },
+            { pattern: '.gpt.md', priority: 2, description: 'Hidden GPT instructions' },
+            { pattern: 'CHATGPT.md', priority: 3, description: 'ChatGPT instructions' },
+        ],
+    },
+    {
+        provider: 'copilot',
+        patterns: [
+            { pattern: 'COPILOT.md', priority: 1, description: 'Copilot project instructions' },
+            { pattern: '.copilot.md', priority: 2, description: 'Hidden Copilot instructions' },
+            {
+                pattern: '.github/copilot-instructions.md',
+                priority: 3,
+                description: 'GitHub Copilot instructions',
+            },
+        ],
+    },
+    {
+        provider: 'cursor',
+        patterns: [
+            { pattern: 'CURSOR.md', priority: 1, description: 'Cursor project instructions' },
+            { pattern: '.cursor.md', priority: 2, description: 'Hidden Cursor instructions' },
+            { pattern: '.cursor/rules', priority: 3, description: 'Cursor rules file' },
+            { pattern: '.cursorrules', priority: 4, description: 'Cursor rules (alt location)' },
+        ],
+    },
+    {
+        provider: 'codeium',
+        patterns: [
+            { pattern: 'CODEIUM.md', priority: 1, description: 'Codeium project instructions' },
+            { pattern: '.codeium.md', priority: 2, description: 'Hidden Codeium instructions' },
+            {
+                pattern: '.codeium/instructions.md',
+                priority: 3,
+                description: 'Codeium directory instructions',
+            },
+        ],
+    },
+];
+/**
+ * Generic patterns that apply to any LLM
+ */
+const GENERIC_PATTERNS = [
+    { pattern: 'PROJECT.md', priority: 10, description: 'Generic project instructions' },
+    { pattern: 'INSTRUCTIONS.md', priority: 11, description: 'Generic instructions' },
+    { pattern: 'AI.md', priority: 12, description: 'AI-specific instructions' },
+    { pattern: 'CONTEXT.md', priority: 13, description: 'Project context' },
+    { pattern: '.ai/instructions.md', priority: 14, description: 'AI directory instructions' },
+    { pattern: '.instructions.md', priority: 15, description: 'Hidden instructions' },
+];
+/**
+ * Default options for ProjectMemoryLoader
+ */
+const DEFAULT_OPTIONS = {
+    providers: 'claude',
+    includeGeneric: true,
+    customPatterns: [],
+    searchParents: true,
+    maxParentDepth: 10,
+    stopAtGitRoot: true,
+    combineStrategy: 'concat',
+    separator: '\n\n---\n\n',
+    maxContentSize: 100000,
+    includeHeaders: true,
+    headerFormat: '# From: {relativePath}\n\n',
+    encoding: 'utf-8',
+};
+/**
+ * ProjectMemoryLoader discovers and loads project-specific instructions
+ */
+export class ProjectMemoryLoader {
+    options;
+    patterns;
+    eventHandlers = new Set();
+    constructor(options = {}) {
+        this.options = { ...DEFAULT_OPTIONS, ...options };
+        // Build pattern list
+        this.patterns = this.buildPatterns();
+    }
+    /**
+     * Build the list of patterns to search for
+     */
+    buildPatterns() {
+        const patterns = [];
+        // Add provider-specific patterns
+        const providers = Array.isArray(this.options.providers)
+            ? this.options.providers
+            : [this.options.providers];
+        for (const provider of providers) {
+            const providerPatterns = PROVIDER_PATTERNS.find((p) => p.provider.toLowerCase() === provider.toLowerCase());
+            if (providerPatterns) {
+                patterns.push(...providerPatterns.patterns);
+            }
+            else {
+                // Unknown provider - generate standard patterns
+                const name = provider.toUpperCase();
+                const lower = provider.toLowerCase();
+                patterns.push({ pattern: `${name}.md`, priority: 1, description: `${name} project instructions` }, { pattern: `.${lower}.md`, priority: 2, description: `Hidden ${name} instructions` }, {
+                    pattern: `.${lower}/instructions.md`,
+                    priority: 3,
+                    description: `${name} directory instructions`,
+                });
+            }
+        }
+        // Add generic patterns if enabled
+        if (this.options.includeGeneric) {
+            patterns.push(...GENERIC_PATTERNS);
+        }
+        // Add custom patterns
+        if (this.options.customPatterns.length > 0) {
+            patterns.push(...this.options.customPatterns);
+        }
+        // Sort by priority
+        return patterns.sort((a, b) => a.priority - b.priority);
+    }
+    /**
+     * Load project memory from a directory
+     *
+     * @param rootDir - Starting directory for search
+     * @returns Loaded project memory
+     */
+    async load(rootDir) {
+        const absoluteRoot = path.resolve(rootDir);
+        this.emit({
+            type: 'memory:search_start',
+            rootDir: absoluteRoot,
+            patterns: this.patterns.map((p) => p.pattern),
+        });
+        const files = [];
+        let totalSize = 0;
+        // Get directories to search
+        const directories = await this.getSearchDirectories(absoluteRoot);
+        // Search each directory
+        for (const dir of directories) {
+            for (const pattern of this.patterns) {
+                // Check size limit
+                if (totalSize >= this.options.maxContentSize) {
+                    break;
+                }
+                const filePath = path.join(dir, pattern.pattern);
+                try {
+                    const stat = await fs.stat(filePath);
+                    if (stat.isFile()) {
+                        this.emit({ type: 'memory:file_found', path: filePath, pattern: pattern.pattern });
+                        // Check if adding this file would exceed limit
+                        if (totalSize + stat.size > this.options.maxContentSize) {
+                            this.emit({
+                                type: 'memory:file_skipped',
+                                path: filePath,
+                                reason: 'Would exceed max content size',
+                            });
+                            continue;
+                        }
+                        // Load file content
+                        const content = await fs.readFile(filePath, this.options.encoding);
+                        const memoryFile = {
+                            path: filePath,
+                            content,
+                            relativePath: path.relative(absoluteRoot, filePath),
+                            matchedPattern: pattern.pattern,
+                            size: stat.size,
+                            modifiedAt: stat.mtime,
+                        };
+                        files.push(memoryFile);
+                        totalSize += stat.size;
+                        this.emit({ type: 'memory:file_loaded', file: memoryFile });
+                        // For 'priority' strategy, stop after first file
+                        if (this.options.combineStrategy === 'priority') {
+                            break;
+                        }
+                    }
+                }
+                catch {
+                    // File doesn't exist, continue
+                }
+            }
+            // For 'priority' strategy, stop after first file found
+            if (this.options.combineStrategy === 'priority' && files.length > 0) {
+                break;
+            }
+        }
+        // Combine content
+        const content = this.combineContent(files, absoluteRoot);
+        const memory = {
+            files,
+            content,
+            rootDir: absoluteRoot,
+            estimatedTokens: Math.ceil(content.length / 4),
+        };
+        this.emit({ type: 'memory:search_complete', memory });
+        return memory;
+    }
+    /**
+     * Discover memory files without loading content
+     *
+     * @param rootDir - Starting directory for search
+     * @returns Discovery result with paths
+     */
+    async discover(rootDir) {
+        const absoluteRoot = path.resolve(rootDir);
+        const paths = [];
+        const matchedPatterns = [];
+        const directories = await this.getSearchDirectories(absoluteRoot);
+        for (const dir of directories) {
+            for (const pattern of this.patterns) {
+                const filePath = path.join(dir, pattern.pattern);
+                try {
+                    const stat = await fs.stat(filePath);
+                    if (stat.isFile()) {
+                        paths.push(filePath);
+                        if (!matchedPatterns.includes(pattern.pattern)) {
+                            matchedPatterns.push(pattern.pattern);
+                        }
+                    }
+                }
+                catch {
+                    // File doesn't exist
+                }
+            }
+        }
+        return {
+            paths,
+            found: paths.length > 0,
+            matchedPatterns,
+        };
+    }
+    /**
+     * Get the list of directories to search
+     */
+    async getSearchDirectories(rootDir) {
+        const directories = [rootDir];
+        if (!this.options.searchParents) {
+            return directories;
+        }
+        let currentDir = rootDir;
+        let depth = 0;
+        while (depth < this.options.maxParentDepth) {
+            const parentDir = path.dirname(currentDir);
+            // Stop if we've reached the filesystem root
+            if (parentDir === currentDir) {
+                break;
+            }
+            // Check for git root if configured
+            if (this.options.stopAtGitRoot) {
+                try {
+                    await fs.access(path.join(currentDir, '.git'));
+                    // Found git root, don't search beyond
+                    break;
+                }
+                catch {
+                    // Not a git root, continue
+                }
+            }
+            directories.push(parentDir);
+            currentDir = parentDir;
+            depth++;
+        }
+        return directories;
+    }
+    /**
+     * Combine content from multiple files
+     */
+    combineContent(files, rootDir) {
+        if (files.length === 0) {
+            return '';
+        }
+        if (this.options.combineStrategy === 'priority') {
+            // Just return first file's content
+            const file = files[0];
+            if (this.options.includeHeaders) {
+                const header = this.formatHeader(file, rootDir);
+                return header + file.content;
+            }
+            return file.content;
+        }
+        // For 'concat' and 'dedupe' strategies
+        const parts = [];
+        const seenContent = new Set();
+        for (const file of files) {
+            // Skip duplicates for 'dedupe' strategy
+            if (this.options.combineStrategy === 'dedupe') {
+                const normalized = file.content.trim();
+                if (seenContent.has(normalized)) {
+                    continue;
+                }
+                seenContent.add(normalized);
+            }
+            if (this.options.includeHeaders) {
+                const header = this.formatHeader(file, rootDir);
+                parts.push(header + file.content);
+            }
+            else {
+                parts.push(file.content);
+            }
+        }
+        return parts.join(this.options.separator);
+    }
+    /**
+     * Format the header for a file
+     */
+    formatHeader(file, rootDir) {
+        return this.options.headerFormat
+            .replace('{path}', file.path)
+            .replace('{relativePath}', file.relativePath || path.relative(rootDir, file.path));
+    }
+    /**
+     * Register an event handler
+     */
+    onEvent(handler) {
+        this.eventHandlers.add(handler);
+        return () => this.eventHandlers.delete(handler);
+    }
+    /**
+     * Emit an event
+     */
+    emit(event) {
+        for (const handler of this.eventHandlers) {
+            try {
+                handler(event);
+            }
+            catch {
+                // Ignore handler errors
+            }
+        }
+    }
+    /**
+     * Get the patterns being used
+     */
+    getPatterns() {
+        return [...this.patterns];
+    }
+    /**
+     * Get the configured options
+     */
+    getOptions() {
+        return { ...this.options };
+    }
+}
+/**
+ * Create a ProjectMemoryLoader with default options
+ */
+export function createProjectMemoryLoader(options) {
+    return new ProjectMemoryLoader(options);
+}
+/**
+ * Quick utility to load project memory
+ */
+export async function loadProjectMemory(rootDir, options) {
+    const loader = new ProjectMemoryLoader(options);
+    return loader.load(rootDir);
+}
+/**
+ * Quick utility to check if a directory has project memory files
+ */
+export async function hasProjectMemory(rootDir, options) {
+    const loader = new ProjectMemoryLoader(options);
+    const result = await loader.discover(rootDir);
+    return result.found;
+}
+/**
+ * Get built-in patterns for a provider
+ */
+export function getProviderPatterns(provider) {
+    const found = PROVIDER_PATTERNS.find((p) => p.provider.toLowerCase() === provider.toLowerCase());
+    return found ? [...found.patterns] : [];
+}
+/**
+ * Get all supported provider names
+ */
+export function getSupportedProviders() {
+    return PROVIDER_PATTERNS.map((p) => p.provider);
+}
+/**
+ * Get generic patterns
+ */
+export function getGenericPatterns() {
+    return [...GENERIC_PATTERNS];
+}
+// Export built-in patterns for reference
+export { PROVIDER_PATTERNS, GENERIC_PATTERNS };