@nexus-cortex/core 4.26.0

package/dist/system-messages/MessageValidator.js

@@ -0,0 +1,305 @@
+/**
+ * Message Validator
+ *
+ * Validates system message files before loading/hot-reloading.
+ * Ensures messages are safe and well-formed.
+ */
+import * as fs from 'fs/promises';
+/**
+ * Message Validator
+ *
+ * Validates message files for:
+ * - File size limits
+ * - Valid UTF-8 encoding
+ * - No dangerous injection patterns
+ * - Optional frontmatter parsing
+ * - Markdown syntax validation
+ */
+export class MessageValidator {
+    config;
+    constructor(config = {}) {
+        this.config = {
+            maxFileSize: config.maxFileSize ?? 1_000_000, // 1MB
+            maxLineLength: config.maxLineLength ?? 10_000,
+            strict: config.strict ?? false,
+            enableSecurityChecks: config.enableSecurityChecks ?? true,
+        };
+    }
+    /**
+     * Validate a message file
+     */
+    async validate(filePath) {
+        const errors = [];
+        const warnings = [];
+        try {
+            // Read file
+            const content = await fs.readFile(filePath, 'utf-8');
+            const stats = this.calculateStats(content);
+            // Check file size
+            if (content.length > this.config.maxFileSize) {
+                errors.push({
+                    type: 'size',
+                    message: `File exceeds maximum size of ${this.formatSize(this.config.maxFileSize)}`,
+                });
+            }
+            // Check encoding (UTF-8 validation)
+            if (!this.isValidUTF8(content)) {
+                errors.push({
+                    type: 'encoding',
+                    message: 'File contains invalid UTF-8 sequences',
+                });
+            }
+            // Check for control characters (except newlines, tabs)
+            const controlChars = this.findControlCharacters(content);
+            if (controlChars.length > 0) {
+                errors.push({
+                    type: 'encoding',
+                    message: `File contains ${controlChars.length} invalid control character(s)`,
+                });
+            }
+            // Parse and validate frontmatter (optional)
+            const frontmatterResult = this.parseFrontmatter(content);
+            if (frontmatterResult.error) {
+                if (this.config.strict) {
+                    errors.push({
+                        type: 'frontmatter',
+                        message: frontmatterResult.error,
+                        line: frontmatterResult.line,
+                    });
+                }
+                else {
+                    warnings.push({
+                        type: 'formatting',
+                        message: `Frontmatter issue: ${frontmatterResult.error}`,
+                    });
+                }
+            }
+            // Security checks
+            if (this.config.enableSecurityChecks) {
+                const securityIssues = this.findSecurityIssues(content);
+                if (securityIssues.length > 0) {
+                    errors.push({
+                        type: 'security',
+                        message: `Found ${securityIssues.length} potential security issue(s): ${securityIssues.join(', ')}`,
+                    });
+                }
+            }
+            // Check line lengths
+            const longLines = this.findLongLines(content);
+            if (longLines.length > 0) {
+                if (this.config.strict) {
+                    errors.push({
+                        type: 'syntax',
+                        message: `${longLines.length} line(s) exceed ${this.config.maxLineLength} characters`,
+                        line: longLines[0],
+                    });
+                }
+                else {
+                    warnings.push({
+                        type: 'formatting',
+                        message: `${longLines.length} very long line(s) found`,
+                        suggestion: 'Consider breaking long lines for readability',
+                    });
+                }
+            }
+            // Warn if file is very large
+            if (content.length > 100_000 && content.length <= this.config.maxFileSize) {
+                warnings.push({
+                    type: 'length',
+                    message: `Large file (${this.formatSize(content.length)})`,
+                    suggestion: 'Consider breaking into multiple focused messages',
+                });
+            }
+            // Warn if file is empty
+            if (content.trim().length === 0) {
+                warnings.push({
+                    type: 'length',
+                    message: 'File is empty',
+                });
+            }
+            return {
+                valid: errors.length === 0,
+                errors,
+                warnings,
+                stats,
+            };
+        }
+        catch (error) {
+            return {
+                valid: false,
+                errors: [
+                    {
+                        type: 'syntax',
+                        message: `Failed to read/parse file: ${error.message}`,
+                    },
+                ],
+                warnings: [],
+                stats: { lines: 0, chars: 0, words: 0 },
+            };
+        }
+    }
+    /**
+     * Validate content string (without file I/O)
+     */
+    validateContent(content) {
+        const errors = [];
+        const warnings = [];
+        const stats = this.calculateStats(content);
+        // Same validation as file, but on content directly
+        if (content.length > this.config.maxFileSize) {
+            errors.push({
+                type: 'size',
+                message: `Content exceeds maximum size of ${this.formatSize(this.config.maxFileSize)}`,
+            });
+        }
+        if (!this.isValidUTF8(content)) {
+            errors.push({
+                type: 'encoding',
+                message: 'Content contains invalid UTF-8 sequences',
+            });
+        }
+        const controlChars = this.findControlCharacters(content);
+        if (controlChars.length > 0) {
+            errors.push({
+                type: 'encoding',
+                message: `Content contains ${controlChars.length} invalid control character(s)`,
+            });
+        }
+        if (this.config.enableSecurityChecks) {
+            const securityIssues = this.findSecurityIssues(content);
+            if (securityIssues.length > 0) {
+                errors.push({
+                    type: 'security',
+                    message: `Found ${securityIssues.length} potential security issue(s): ${securityIssues.join(', ')}`,
+                });
+            }
+        }
+        return {
+            valid: errors.length === 0,
+            errors,
+            warnings,
+            stats,
+        };
+    }
+    /**
+     * Check if string is valid UTF-8
+     */
+    isValidUTF8(str) {
+        try {
+            // Try to encode and decode
+            const encoder = new TextEncoder();
+            const decoder = new TextDecoder('utf-8', { fatal: true });
+            const encoded = encoder.encode(str);
+            decoder.decode(encoded);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Find control characters (except \n, \r, \t)
+     */
+    findControlCharacters(content) {
+        const positions = [];
+        for (let i = 0; i < content.length; i++) {
+            const code = content.charCodeAt(i);
+            // Control characters: 0x00-0x1F, excluding \n (0x0A), \r (0x0D), \t (0x09)
+            if (code < 0x20 && code !== 0x0a && code !== 0x0d && code !== 0x09) {
+                positions.push(i);
+            }
+        }
+        return positions;
+    }
+    /**
+     * Parse frontmatter (YAML between --- markers)
+     */
+    parseFrontmatter(content) {
+        const lines = content.split('\n');
+        // Check if starts with frontmatter
+        if (!lines[0]?.trim().startsWith('<!--') || !content.includes('-->')) {
+            return {}; // No frontmatter
+        }
+        try {
+            // Extract HTML comment frontmatter
+            const commentMatch = content.match(/<!--([\s\S]*?)-->/);
+            if (!commentMatch) {
+                return {};
+            }
+            // Very basic parsing - just check it's reasonable
+            const commentContent = commentMatch[1];
+            if (commentContent && commentContent.length > 10000) {
+                return {
+                    error: 'Frontmatter too large',
+                    line: 1,
+                };
+            }
+            return {};
+        }
+        catch (error) {
+            return {
+                error: error.message,
+                line: 1,
+            };
+        }
+    }
+    /**
+     * Find potential security issues
+     */
+    findSecurityIssues(content) {
+        const issues = [];
+        // Check for script injection patterns
+        if (/<script[\s>]/i.test(content)) {
+            issues.push('script tags detected');
+        }
+        // Check for eval/Function patterns (JavaScript injection)
+        if (/\beval\s*\(|\bFunction\s*\(/i.test(content)) {
+            issues.push('eval/Function calls detected');
+        }
+        // Check for file:// protocol (local file access)
+        if (/file:\/\//i.test(content)) {
+            issues.push('file:// protocol detected');
+        }
+        // Check for shell command patterns (basic check)
+        if (/\$\{|\$\(|`.*`/.test(content)) {
+            // Only flag if it looks like shell interpolation
+            if (/\$\{[^}]*\}|\$\([^)]*\)|`[^`]*`/.test(content)) {
+                issues.push('potential shell command interpolation');
+            }
+        }
+        return issues;
+    }
+    /**
+     * Find lines exceeding max length
+     */
+    findLongLines(content) {
+        const lines = content.split('\n');
+        const longLines = [];
+        for (let i = 0; i < lines.length; i++) {
+            if (lines[i].length > this.config.maxLineLength) {
+                longLines.push(i + 1); // 1-indexed
+            }
+        }
+        return longLines;
+    }
+    /**
+     * Calculate content statistics
+     */
+    calculateStats(content) {
+        const lines = content.split('\n').length;
+        const chars = content.length;
+        const words = content.split(/\s+/).filter((w) => w.length > 0).length;
+        return { lines, chars, words };
+    }
+    /**
+     * Format byte size for display
+     */
+    formatSize(bytes) {
+        if (bytes < 1024)
+            return `${bytes} bytes`;
+        if (bytes < 1024 * 1024)
+            return `${(bytes / 1024).toFixed(1)} KB`;
+        return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+    }
+}
+//# sourceMappingURL=MessageValidator.js.map

package/dist/system-messages/MessageValidator.js.map

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

package/dist/system-messages/SystemMessageLoader.d.ts

@@ -0,0 +1,154 @@
+/**
+ * System Message Loader - Simplified Direct File Loading
+ *
+ * Loads system messages directly from files on each injection.
+ * Three-tier lookup priority:
+ *   1. Project level: {projectPath}/.cortex/system-messages/
+ *   2. Global default: ~/.cortex/system-messages/
+ *   3. Built-in: packages/core/dist/system-messages/messages/
+ *
+ * No caching between turns - always reads fresh from disk.
+ * This allows /system-message edits to take effect on the next turn.
+ */
+import type { SystemMessageDefinition, InjectionContext, LoadedSystemMessage, TemplateVariables, SystemMessageForInjection } from './SystemMessageRegistry.interface.js';
+/**
+ * System Message Loader Options
+ */
+export interface SystemMessageLoaderOptions {
+    /** Project root path (for .cortex/system-messages/) */
+    projectPath?: string;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+/**
+ * System Message Loader
+ * Simple, direct file loading with project-level overrides
+ */
+export declare class SystemMessageLoader {
+    private registry;
+    private lastInjectedHashes;
+    /**
+     * mtime-keyed cache for file content. The orchestrator calls
+     * `getMessagesForInjection` once per turn, which fans out to 5+
+     * `fs.readFile` calls for CLAUDE.md / MEMORY.md / CORTEX.md / AGENTS.md /
+     * GEMINI.md. Without caching this is pure waste — those files don't
+     * change between turns under normal use.
+     *
+     * Invalidation: per-file mtime check (one `stat` call) before returning
+     * cached content. A `stat` is roughly 10× cheaper than reading a 30KB
+     * file, and edits land on the next turn because we re-read on mtime
+     * change. Hot-reload semantics preserved.
+     */
+    private fileContentCache;
+    private readonly builtinPath;
+    private readonly debug;
+    private projectPath;
+    constructor(options?: SystemMessageLoaderOptions);
+    /**
+     * Update project path (called when session context changes)
+     */
+    setProjectPath(projectPath: string): void;
+    /**
+     * Load the registry configuration
+     */
+    loadRegistry(): Promise<void>;
+    /**
+     * Get registry (load if not loaded)
+     */
+    private getRegistry;
+    /**
+     * Load user registry from .cortex/registry.json
+     * Returns a map of message ID to registry entry for easy lookup
+     */
+    private loadUserRegistry;
+    /**
+     * Create a SystemMessageDefinition from a user registry entry
+     * Used for user-created messages that don't exist in built-in registry
+     */
+    private createDefinitionFromUserEntry;
+    /**
+     * Check if file exists
+     */
+    private fileExists;
+    /**
+     * Read file content, with mtime-keyed caching.
+     *
+     * Replaces ~5 raw `readFile` calls per turn (CLAUDE.md/MEMORY.md/etc.)
+     * with a `stat`+cache lookup. On cache hit, no disk read at all. On miss
+     * or mtime change, reads fresh and updates the cache.
+     *
+     * Throws on missing file (matches `readFile` semantics) so existing call
+     * sites that already gate on `fileExists` can drop this in unchanged.
+     */
+    private readFileCached;
+    /**
+     * Load message content with three-tier lookup:
+     * 1. Project .cortex/system-messages/{file}
+     * 2. Global ~/.cortex/system-messages/{file}
+     * 3. Built-in messages/{file}
+     *
+     * Special case for CORTEX.md: loads from .cortex/CORTEX.md with global fallback
+     */
+    private loadMessageFile;
+    /**
+     * #28: optional per-doc byte cap.
+     *
+     * Only applies to the large project-doc injectors (CLAUDE.md, MEMORY.md,
+     * AGENTS.md, GEMINI.md, CORTEX.md). Smaller built-in messages
+     * (SYSTEM_PROMPT.md, TOOL_USAGE_GUIDE.md, etc.) are untouched — they're
+     * already tightly authored.
+     *
+     * Defaults to "no cap" when SYSTEM_MESSAGE_DOC_MAX_BYTES is unset/0, so
+     * existing deployments keep current behavior. Operators opt in by setting
+     * a positive integer.
+     */
+    private static readonly CAPPED_DOC_IDS;
+    private maybeCapDocContent;
+    /**
+     * Apply template variables to content
+     */
+    private applyTemplates;
+    /**
+     * Generate content hash for deduplication
+     */
+    private generateContentHash;
+    /**
+     * Check if injection conditions are met
+     */
+    private checkConditions;
+    /**
+     * Get messages to inject for given context
+     * Reads fresh from disk each time - no caching
+     * Merges user registry overrides with built-in definitions
+     */
+    getMessagesForContext(context: InjectionContext, templateVars?: TemplateVariables): Promise<LoadedSystemMessage[]>;
+    /**
+     * Clear deduplication tracking (call between turns if needed)
+     */
+    clearDeduplication(): void;
+    /**
+     * Reload registry
+     */
+    reload(): Promise<void>;
+    /**
+     * Get specific message by ID
+     */
+    getMessageById(id: string, templateVars?: TemplateVariables): Promise<LoadedSystemMessage | null>;
+    /**
+     * Get messages formatted for injection into content array
+     */
+    getMessagesForInjection(context: InjectionContext, templateVars?: TemplateVariables): Promise<SystemMessageForInjection[]>;
+    /**
+     * List all registered message definitions
+     */
+    listMessages(): Promise<SystemMessageDefinition[]>;
+    /**
+     * Get project-level system messages directory
+     */
+    getProjectMessagesDir(): string;
+    /**
+     * Get built-in system messages directory
+     */
+    getBuiltinMessagesDir(): string;
+}
+//# sourceMappingURL=SystemMessageLoader.d.ts.map

package/dist/system-messages/SystemMessageLoader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SystemMessageLoader.d.ts","sourceRoot":"","sources":["../../src/system-messages/SystemMessageLoader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH,OAAO,KAAK,EAEV,uBAAuB,EACvB,gBAAgB,EAChB,mBAAmB,EACnB,iBAAiB,EACjB,yBAAyB,EAC1B,MAAM,sCAAsC,CAAC;AAiB9C;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC,uDAAuD;IACvD,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,2BAA2B;IAC3B,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;GAGG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAA4C;IAC5D,OAAO,CAAC,kBAAkB,CAAqB;IAE/C;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,gBAAgB,CAA2D;IAEnF,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAU;IAChC,OAAO,CAAC,WAAW,CAAS;gBAEhB,OAAO,GAAE,0BAA+B;IAMpD;;OAEG;IACH,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAOzC;;OAEG;IACG,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAgBnC;;OAEG;YACW,WAAW;IAOzB;;;OAGG;YACW,gBAAgB;IAyB9B;;;OAGG;IACH,OAAO,CAAC,6BAA6B;IAiCrC;;OAEG;YACW,UAAU;IASxB;;;;;;;;;OASG;YACW,cAAc;IAc5B;;;;;;;OAOG;YACW,eAAe;IAwO7B;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,cAAc,CAMnC;IAEH,OAAO,CAAC,kBAAkB;IAW1B;;OAEG;IACH,OAAO,CAAC,cAAc;IAYtB;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAO3B;;OAEG;IACH,OAAO,CAAC,eAAe;IA2DvB;;;;OAIG;IACG,qBAAqB,CACzB,OAAO,EAAE,gBAAgB,EACzB,YAAY,GAAE,iBAAsB,GACnC,OAAO,CAAC,mBAAmB,EAAE,CAAC;IAmIjC;;OAEG;IACH,kBAAkB,IAAI,IAAI;IAI1B;;OAEG;IACG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAM7B;;OAEG;IACG,cAAc,CAAC,EAAE,EAAE,MAAM,EAAE,YAAY,GAAE,iBAAsB,GAAG,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC;IA6B3G;;OAEG;IACG,uBAAuB,CAC3B,OAAO,EAAE,gBAAgB,EACzB,YAAY,GAAE,iBAAsB,GACnC,OAAO,CAAC,yBAAyB,EAAE,CAAC;IAavC;;OAEG;IACG,YAAY,IAAI,OAAO,CAAC,uBAAuB,EAAE,CAAC;IAKxD;;OAEG;IACH,qBAAqB,IAAI,MAAM;IAI/B;;OAEG;IACH,qBAAqB,IAAI,MAAM;CAGhC"}