grimoire-framework 1.0.0

package/packages/installer/src/merger/index.js

@@ -0,0 +1,72 @@
+/**
+ * @fileoverview Smart Merge Module for grimoire Installer
+ *
+ * This module provides intelligent merging capabilities for configuration files
+ * during grimoire installation in brownfield projects. Instead of overwriting
+ * existing files, it can merge new content while preserving user customizations.
+ *
+ * Supported file types:
+ * - .env files: Key-based merge (adds new variables, preserves existing)
+ * - .md files: Section-based merge using grimoire-MANAGED markers
+ *
+ * @module merger
+ * @example
+ * const { getMergeStrategy, hasMergeStrategy } = require('./merger/index.js');
+ *
+ * // Check if merge is available for a file
+ * if (hasMergeStrategy('.env')) {
+ *   const merger = getMergeStrategy('.env');
+ *   const result = await merger.merge(existingContent, newContent);
+ *   console.log(`Preserved: ${result.stats.preserved}, Added: ${result.stats.added}`);
+ * }
+ */
+
+// Re-export strategy factory functions
+const {
+  getMergeStrategy,
+  hasMergeStrategy,
+  registerStrategy,
+  registerFileNameStrategy,
+  getSupportedTypes,
+  BaseMerger,
+  ReplaceMerger,
+  EnvMerger,
+  MarkdownMerger,
+} = require('./strategies/index.js');
+
+// Re-export types and utilities
+const { createEmptyStats, createMergeResult } = require('./types.js');
+
+// Re-export parsers for testing/extension
+const { parseEnvFile } = require('./parsers/env-parser.js');
+const {
+  parseMarkdownSections,
+  slugify,
+  hasgrimoireMarkers,
+} = require('./parsers/markdown-section-parser.js');
+
+module.exports = {
+  // Strategy factory
+  getMergeStrategy,
+  hasMergeStrategy,
+  registerStrategy,
+  registerFileNameStrategy,
+  getSupportedTypes,
+
+  // Types and utilities
+  createEmptyStats,
+  createMergeResult,
+
+  // Base classes for extension
+  BaseMerger,
+  ReplaceMerger,
+  EnvMerger,
+  MarkdownMerger,
+
+  // Parsers
+  parseEnvFile,
+  parseMarkdownSections,
+  slugify,
+  hasgrimoireMarkers,
+};
+

package/packages/installer/src/merger/parsers/env-parser.js

@@ -0,0 +1,153 @@
+/**
+ * @fileoverview Parser for .env files
+ * @module merger/parsers/env-parser
+ */
+
+/**
+ * Parsed variable from .env file
+ * @typedef {Object} ParsedVariable
+ * @property {string} value - Variable value
+ * @property {number} line - Line number (0-indexed)
+ * @property {string|null} comment - Associated comment (line above)
+ * @property {string} rawLine - Original line as written
+ */
+
+/**
+ * Structure item in the parsed result
+ * @typedef {Object} StructureItem
+ * @property {'comment'|'blank'|'variable'} type - Type of line
+ * @property {string} content - Original line content
+ * @property {number} line - Line number (0-indexed)
+ * @property {string} [key] - Variable key (only for type='variable')
+ */
+
+/**
+ * Result of parsing an .env file
+ * @typedef {Object} ParsedEnvFile
+ * @property {Map<string, ParsedVariable>} variables - Map of variable name to parsed info
+ * @property {StructureItem[]} structure - Ordered structure of the file
+ * @property {string[]} rawLines - Original lines
+ * @property {string[]} comments - All comment lines
+ */
+
+/**
+ * Parse an .env file content
+ * @param {string} content - Content of the .env file
+ * @returns {ParsedEnvFile} Parsed result
+ */
+function parseEnvFile(content) {
+  // Handle empty content
+  if (!content || content.trim() === '') {
+    return {
+      variables: new Map(),
+      structure: [],
+      rawLines: [],
+      comments: [],
+    };
+  }
+
+  const lines = content.split('\n');
+  const result = {
+    variables: new Map(),
+    structure: [],
+    rawLines: lines,
+    comments: [],
+  };
+
+  let currentComment = null;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const trimmed = line.trim();
+
+    // Empty line
+    if (trimmed === '') {
+      result.structure.push({
+        type: 'blank',
+        content: '',
+        line: i,
+      });
+      currentComment = null;
+      continue;
+    }
+
+    // Comment line
+    if (trimmed.startsWith('#')) {
+      result.structure.push({
+        type: 'comment',
+        content: line,
+        line: i,
+      });
+      result.comments.push(trimmed);
+      currentComment = trimmed;
+      continue;
+    }
+
+    // Variable line - handle KEY=VALUE format
+    const equalsIndex = trimmed.indexOf('=');
+    if (equalsIndex > 0) {
+      const key = trimmed.substring(0, equalsIndex).trim();
+      const value = trimmed.substring(equalsIndex + 1);
+
+      // Only add valid variable names (alphanumeric + underscore, starting with letter/underscore)
+      if (/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(key)) {
+        result.variables.set(key, {
+          value: value,
+          line: i,
+          comment: currentComment,
+          rawLine: line,
+        });
+
+        result.structure.push({
+          type: 'variable',
+          content: line,
+          line: i,
+          key: key,
+        });
+      } else {
+        // Invalid key, treat as comment/text
+        result.structure.push({
+          type: 'comment',
+          content: line,
+          line: i,
+        });
+      }
+
+      currentComment = null;
+    } else {
+      // Line without '=' - treat as comment
+      result.structure.push({
+        type: 'comment',
+        content: line,
+        line: i,
+      });
+      currentComment = null;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Check if a string is a valid .env variable name
+ * @param {string} name - Variable name to check
+ * @returns {boolean} True if valid
+ */
+function isValidEnvVarName(name) {
+  return /^[a-zA-Z_][a-zA-Z0-9_]*$/.test(name);
+}
+
+/**
+ * Reconstruct .env content from parsed structure
+ * @param {ParsedEnvFile} parsed - Parsed env file
+ * @returns {string} Reconstructed content
+ */
+function reconstructEnvFile(parsed) {
+  return parsed.rawLines.join('\n');
+}
+
+module.exports = {
+  parseEnvFile,
+  isValidEnvVarName,
+  reconstructEnvFile,
+};

package/packages/installer/src/merger/parsers/markdown-section-parser.js

@@ -0,0 +1,199 @@
+/**
+ * @fileoverview Parser for Markdown files with grimoire-MANAGED sections
+ * @module merger/parsers/markdown-section-parser
+ */
+
+// Regex patterns for grimoire markers
+const grimoire_START_MARKER = /^<!--\s*grimoire-MANAGED-START:\s*([a-zA-Z0-9_-]+)\s*-->$/;
+const grimoire_END_MARKER = /^<!--\s*grimoire-MANAGED-END:\s*([a-zA-Z0-9_-]+)\s*-->$/;
+const HEADER_PATTERN = /^(#{1,6})\s+(.+)$/;
+
+/**
+ * Parsed section from markdown
+ * @typedef {Object} ParsedSection
+ * @property {string} id - Section identifier (slug or marker id)
+ * @property {string} [title] - Section title (from header)
+ * @property {number} [level] - Header level (1-6)
+ * @property {number} startLine - Start line number (0-indexed)
+ * @property {number} [endLine] - End line number (0-indexed)
+ * @property {boolean} managed - True if grimoire-MANAGED section
+ * @property {string[]} lines - Lines in this section (excluding markers)
+ */
+
+/**
+ * Result of parsing a markdown file
+ * @typedef {Object} ParsedMarkdownFile
+ * @property {ParsedSection[]} sections - All sections found
+ * @property {boolean} hasgrimoireMarkers - True if file has grimoire-MANAGED markers
+ * @property {string[]} preamble - Lines before first section
+ * @property {string[]} rawLines - Original lines
+ */
+
+/**
+ * Convert a string to a URL-friendly slug
+ * @param {string} text - Text to slugify
+ * @returns {string} Slugified text
+ */
+function slugify(text) {
+  return text
+    .toLowerCase()
+    .trim()
+    .replace(/[^\w\s-]/g, '') // Remove special chars
+    .replace(/[\s_-]+/g, '-') // Replace spaces/underscores with hyphens
+    .replace(/^-+|-+$/g, ''); // Remove leading/trailing hyphens
+}
+
+/**
+ * Parse a markdown file, identifying sections and grimoire-MANAGED areas
+ * @param {string} content - Markdown content
+ * @returns {ParsedMarkdownFile} Parsed result
+ */
+function parseMarkdownSections(content) {
+  if (!content || content.trim() === '') {
+    return {
+      sections: [],
+      hasgrimoireMarkers: false,
+      preamble: [],
+      rawLines: [],
+    };
+  }
+
+  const lines = content.split('\n');
+  const result = {
+    sections: [],
+    hasgrimoireMarkers: false,
+    preamble: [],
+    rawLines: lines,
+  };
+
+  let currentSection = null;
+  let grimoireSection = null;
+  let inPreamble = true;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const trimmed = line.trim();
+
+    // Check for grimoire start marker
+    const startMatch = trimmed.match(grimoire_START_MARKER);
+    if (startMatch) {
+      // Close any current non-managed section
+      if (currentSection && !currentSection.managed) {
+        currentSection.endLine = i - 1;
+        result.sections.push(currentSection);
+        currentSection = null;
+      }
+
+      // Start new grimoire-managed section
+      grimoireSection = {
+        id: startMatch[1],
+        startLine: i,
+        managed: true,
+        lines: [],
+      };
+      result.hasgrimoireMarkers = true;
+      inPreamble = false;
+      continue;
+    }
+
+    // Check for grimoire end marker
+    const endMatch = trimmed.match(grimoire_END_MARKER);
+    if (endMatch && grimoireSection) {
+      if (endMatch[1] === grimoireSection.id) {
+        grimoireSection.endLine = i;
+        result.sections.push(grimoireSection);
+        grimoireSection = null;
+      }
+      continue;
+    }
+
+    // If we're in an grimoire section, collect lines
+    if (grimoireSection) {
+      grimoireSection.lines.push(line);
+      continue;
+    }
+
+    // Check for regular header
+    const headerMatch = line.match(HEADER_PATTERN);
+    if (headerMatch) {
+      // Close any current section
+      if (currentSection) {
+        currentSection.endLine = i - 1;
+        result.sections.push(currentSection);
+      }
+
+      // Start new section
+      currentSection = {
+        id: slugify(headerMatch[2]),
+        title: headerMatch[2],
+        level: headerMatch[1].length,
+        startLine: i,
+        managed: false,
+        lines: [line],
+      };
+      inPreamble = false;
+      continue;
+    }
+
+    // Regular content line
+    if (inPreamble) {
+      result.preamble.push(line);
+    } else if (currentSection) {
+      currentSection.lines.push(line);
+    } else if (!grimoireSection) {
+      // Content after an grimoire section but before next section
+      // This shouldn't happen in well-formed files, but handle it
+      result.preamble.push(line);
+    }
+  }
+
+  // Close final section if open
+  if (currentSection) {
+    currentSection.endLine = lines.length - 1;
+    result.sections.push(currentSection);
+  }
+
+  // Handle unclosed grimoire section (malformed)
+  if (grimoireSection) {
+    grimoireSection.endLine = lines.length - 1;
+    grimoireSection.lines.push('<!-- WARNING: Unclosed grimoire-MANAGED section -->');
+    result.sections.push(grimoireSection);
+  }
+
+  return result;
+}
+
+/**
+ * Check if content has grimoire-MANAGED markers
+ * @param {string} content - Markdown content
+ * @returns {boolean} True if markers found
+ */
+function hasgrimoireMarkers(content) {
+  if (!content) return false;
+  // Check for both START and END markers
+  const hasStart = /<!--\s*grimoire-MANAGED-START:\s*[a-zA-Z0-9_-]+\s*-->/.test(content);
+  const hasEnd = /<!--\s*grimoire-MANAGED-END:\s*[a-zA-Z0-9_-]+\s*-->/.test(content);
+  return hasStart && hasEnd;
+}
+
+/**
+ * Get all grimoire section IDs from content
+ * @param {string} content - Markdown content
+ * @returns {string[]} Array of section IDs
+ */
+function getgrimoireSectionIds(content) {
+  const ids = [];
+  const matches = content.matchAll(/<!--\s*grimoire-MANAGED-START:\s*([a-zA-Z0-9_-]+)\s*-->/g);
+  for (const match of matches) {
+    ids.push(match[1]);
+  }
+  return ids;
+}
+
+module.exports = {
+  slugify,
+  parseMarkdownSections,
+  hasgrimoireMarkers,
+  getgrimoireSectionIds,
+};
+

package/packages/installer/src/merger/strategies/base-merger.js

@@ -0,0 +1,61 @@
+/**
+ * @fileoverview Base class for all merge strategies
+ * @module merger/strategies/base-merger
+ */
+
+/**
+ * Abstract base class for merge strategies.
+ * All merger implementations should extend this class.
+ * @abstract
+ */
+class BaseMerger {
+  /**
+   * Name of this merge strategy for logging
+   * @type {string}
+   */
+  name = 'base';
+
+  /**
+   * Check if this strategy can merge the given content
+   * @param {string} existingContent - Content of the existing file
+   * @param {string} newContent - Content to merge in
+   * @returns {boolean} True if merge is possible
+   * @abstract
+   */
+  canMerge(_existingContent, _newContent) {
+    throw new Error('BaseMerger.canMerge() must be implemented by subclass');
+  }
+
+  /**
+   * Merge existing content with new content
+   * @param {string} existingContent - Content of the existing file
+   * @param {string} newContent - Content to merge in
+   * @param {import('../types.js').MergeOptions} [options] - Merge options
+   * @returns {Promise<import('../types.js').MergeResult>} Merge result
+   * @abstract
+   */
+  async merge(_existingContent, _newContent, _options = {}) {
+    throw new Error('BaseMerger.merge() must be implemented by subclass');
+  }
+
+  /**
+   * Preview merge without applying changes
+   * Returns the same result as merge() but with preview flag set
+   * @param {string} existingContent - Content of the existing file
+   * @param {string} newContent - Content to merge in
+   * @returns {Promise<import('../types.js').MergeResult>} Preview of merge result
+   */
+  async preview(existingContent, newContent) {
+    return this.merge(existingContent, newContent, { preview: true });
+  }
+
+  /**
+   * Get a description of what this strategy does
+   * @returns {string} Human-readable description
+   */
+  getDescription() {
+    return `${this.name} merge strategy`;
+  }
+}
+
+module.exports = { BaseMerger };

package/packages/installer/src/merger/strategies/env-merger.js

@@ -0,0 +1,138 @@
+/**
+ * @fileoverview Merge strategy for .env files
+ * @module merger/strategies/env-merger
+ */
+
+const { BaseMerger } = require('./base-merger.js');
+const { createMergeResult, createEmptyStats } = require('../types.js');
+const { parseEnvFile } = require('../parsers/env-parser.js');
+
+/**
+ * Merge strategy for .env files.
+ * Preserves existing variables and adds new ones from the template.
+ * @extends BaseMerger
+ */
+class EnvMerger extends BaseMerger {
+  name = 'env';
+
+  /**
+   * Can always merge .env files
+   * @returns {boolean} Always true
+   */
+  canMerge() {
+    return true;
+  }
+
+  /**
+   * Merge existing .env with template, preserving existing values
+   * @param {string} existingContent - Existing .env content
+   * @param {string} newContent - Template .env content
+   * @param {import('../types.js').MergeOptions} [options] - Merge options
+   * @returns {Promise<import('../types.js').MergeResult>} Merge result
+   */
+  async merge(existingContent, newContent, _options = {}) {
+    const existing = parseEnvFile(existingContent);
+    const template = parseEnvFile(newContent);
+
+    const stats = createEmptyStats();
+    const changes = [];
+    const newVars = [];
+    const suggestions = [];
+
+    // Find variables to add from template
+    for (const [key, templateVar] of template.variables) {
+      if (!existing.variables.has(key)) {
+        // New variable - will be added
+        newVars.push({
+          key,
+          value: templateVar.value,
+          comment: templateVar.comment,
+        });
+        changes.push({
+          type: 'added',
+          identifier: key,
+        });
+        stats.added++;
+      } else {
+        // Variable exists - check if value differs
+        const existingVar = existing.variables.get(key);
+        if (existingVar.value !== templateVar.value) {
+          // Different value - preserve existing, suggest new
+          suggestions.push({
+            key,
+            currentValue: existingVar.value,
+            suggestedValue: templateVar.value,
+          });
+          changes.push({
+            type: 'preserved',
+            identifier: key,
+            reason: 'existing value kept, different from template',
+          });
+          stats.conflicts++;
+        } else {
+          // Same value - just preserve
+          changes.push({
+            type: 'preserved',
+            identifier: key,
+          });
+        }
+        stats.preserved++;
+      }
+    }
+
+    // Count preserved variables not in template
+    for (const [key] of existing.variables) {
+      if (!template.variables.has(key)) {
+        changes.push({
+          type: 'preserved',
+          identifier: key,
+          reason: 'user variable (not in template)',
+        });
+        stats.preserved++;
+      }
+    }
+
+    // Build merged content
+    let merged = existingContent;
+
+    // Ensure trailing newline
+    if (merged && !merged.endsWith('\n')) {
+      merged += '\n';
+    }
+
+    // Add grimoire section if there are new vars or suggestions
+    if (newVars.length > 0 || suggestions.length > 0) {
+      const date = new Date().toISOString().split('T')[0];
+      merged += `\n# === grimoire Variables (added ${date}) ===\n`;
+
+      // Add new variables
+      for (const { key, value, comment } of newVars) {
+        if (comment && !comment.includes('grimoire')) {
+          // Add original comment if it's not an grimoire header
+          merged += `${comment}\n`;
+        }
+        merged += `${key}=${value}\n`;
+      }
+
+      // Add suggestions for variables with different values
+      if (suggestions.length > 0) {
+        merged += '\n# grimoire_NOTE: The following variables already exist with different values:\n';
+        for (const { key, suggestedValue } of suggestions) {
+          merged += `# grimoire_SUGGESTED: ${key}=${suggestedValue}\n`;
+        }
+      }
+    }
+
+    return createMergeResult(merged, stats, changes);
+  }
+
+  /**
+   * @returns {string} Description of this strategy
+   */
+  getDescription() {
+    return 'Merges .env files by adding new variables while preserving existing values';
+  }
+}
+
+module.exports = { EnvMerger };
+