grimoire-framework 1.0.0

package/.grimoire/core/config/env-interpolator.js

@@ -0,0 +1,122 @@
+/**
+ * Environment Variable Interpolator
+ *
+ * Resolves ${ENV_VAR} and ${ENV_VAR:-default} patterns in configuration values.
+ * Applied at load time after merge, per ADR-PRO-002.
+ *
+ * Rules:
+ * - ${VAR}: resolves to process.env.VAR; warns if missing, returns ''
+ * - ${VAR:-default}: resolves to process.env.VAR or 'default' if unset
+ * - Recursive: walks nested objects and arrays
+ * - L1/L2 linting: warnOnCommittedSecrets() flags ${...} in framework/project files
+ *
+ * @module core/config/env-interpolator
+ * @version 1.0.0
+ * @created 2026-02-05 (Story PRO-4)
+ * @see docs/architecture/adr/adr-pro-002-configuration-hierarchy.md
+ */
+
+const { isPlainObject } = require('./merge-utils');
+
+/**
+ * Regex for ${ENV_VAR} and ${ENV_VAR:-default_value}
+ * Captures: group 1 = var name, group 2 = default value (optional, after :-)
+ */
+const ENV_VAR_PATTERN = /\$\{([A-Za-z_][A-Za-z0-9_]*)(?::-(.*?))?\}/g;
+
+/**
+ * Interpolate environment variables in a string value.
+ *
+ * @param {string} value - String potentially containing ${VAR} patterns
+ * @param {Object} options - Options
+ * @param {string[]} options.warnings - Array to collect warning messages
+ * @returns {string} Interpolated string
+ */
+function interpolateString(value, options = {}) {
+  const warnings = options.warnings || [];
+
+  return value.replace(ENV_VAR_PATTERN, (match, varName, defaultValue) => {
+    const envValue = process.env[varName];
+
+    if (envValue !== undefined) {
+      return envValue;
+    }
+
+    if (defaultValue !== undefined) {
+      return defaultValue;
+    }
+
+    // Missing required env var (no default)
+    warnings.push(`Missing environment variable: ${varName} (no default set)`);
+    return '';
+  });
+}
+
+/**
+ * Recursively interpolate environment variables in a config object.
+ *
+ * Walks all nested objects and arrays. Only string values are interpolated.
+ *
+ * @param {*} config - Configuration value (object, array, or scalar)
+ * @param {Object} options - Options
+ * @param {string[]} options.warnings - Array to collect warning messages
+ * @returns {*} Interpolated configuration
+ */
+function interpolateEnvVars(config, options = {}) {
+  const warnings = options.warnings || [];
+
+  if (typeof config === 'string') {
+    return interpolateString(config, { warnings });
+  }
+
+  if (Array.isArray(config)) {
+    return config.map(item => interpolateEnvVars(item, { warnings }));
+  }
+
+  if (isPlainObject(config)) {
+    const result = {};
+    for (const [key, value] of Object.entries(config)) {
+      result[key] = interpolateEnvVars(value, { warnings });
+    }
+    return result;
+  }
+
+  // Numbers, booleans, null — return as-is
+  return config;
+}
+
+/**
+ * Check a config object for ${...} patterns that probably shouldn't be
+ * in committed files (L1/L2). Returns an array of findings.
+ *
+ * @param {Object} config - Configuration to lint
+ * @param {string} sourceFile - File name for reporting
+ * @returns {string[]} Array of warning strings
+ */
+function lintEnvPatterns(config, sourceFile) {
+  const findings = [];
+
+  function walk(obj, path) {
+    if (typeof obj === 'string' && ENV_VAR_PATTERN.test(obj)) {
+      // Reset regex lastIndex after test()
+      ENV_VAR_PATTERN.lastIndex = 0;
+      findings.push(`${sourceFile}: ${path} contains env variable pattern: ${obj}`);
+    } else if (isPlainObject(obj)) {
+      for (const [key, value] of Object.entries(obj)) {
+        walk(value, path ? `${path}.${key}` : key);
+      }
+    } else if (Array.isArray(obj)) {
+      obj.forEach((item, i) => { walk(item, `${path}[${i}]`); });
+    }
+  }
+
+  walk(config, '');
+  return findings;
+}
+
+module.exports = {
+  interpolateEnvVars,
+  interpolateString,
+  lintEnvPatterns,
+  ENV_VAR_PATTERN,
+};

package/.grimoire/core/config/merge-utils.js

@@ -0,0 +1,101 @@
+/**
+ * Merge Utilities for Layered Configuration
+ *
+ * Implements the merge strategy defined in ADR-PRO-002:
+ * - Scalars: last-wins
+ * - Objects: deep merge
+ * - Arrays: replace (default)
+ * - Arrays with +append: concatenate
+ * - null values: delete key
+ *
+ * @module core/config/merge-utils
+ * @version 1.0.0
+ * @created 2026-02-05 (Story PRO-4)
+ * @see docs/architecture/adr/adr-pro-002-configuration-hierarchy.md
+ */
+
+/**
+ * Check if value is a plain object (not array, null, Date, etc.)
+ *
+ * @param {*} value - Value to check
+ * @returns {boolean} True if plain object
+ */
+function isPlainObject(value) {
+  if (value === null || typeof value !== 'object') return false;
+  if (Array.isArray(value)) return false;
+
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+
+/**
+ * Deep merge two configuration objects following ADR-PRO-002 rules.
+ *
+ * Merge strategy:
+ * - Scalars (string, number, boolean): last-wins (source overrides target)
+ * - Objects/Maps: recursive deep merge
+ * - Arrays (default): replace (source replaces target)
+ * - Arrays with +append suffix: concatenate source onto target
+ * - null values: delete the key from result
+ *
+ * @param {Object} target - Base configuration (lower priority)
+ * @param {Object} source - Override configuration (higher priority)
+ * @returns {Object} Merged configuration (new object, inputs unchanged)
+ */
+function deepMerge(target, source) {
+  if (!isPlainObject(target) || !isPlainObject(source)) {
+    return source !== undefined ? source : target;
+  }
+
+  const result = { ...target };
+
+  for (const [key, value] of Object.entries(source)) {
+    // Handle +append modifier for arrays
+    if (key.endsWith('+append')) {
+      const baseKey = key.slice(0, -7); // Remove '+append'
+      if (Array.isArray(value)) {
+        const existing = result[baseKey];
+        result[baseKey] = Array.isArray(existing)
+          ? [...existing, ...value]
+          : value;
+      }
+      continue;
+    }
+
+    // Handle null = delete key
+    if (value === null) {
+      delete result[key];
+      continue;
+    }
+
+    // Deep merge plain objects
+    if (isPlainObject(value) && isPlainObject(result[key])) {
+      result[key] = deepMerge(result[key], value);
+      continue;
+    }
+
+    // Arrays and scalars: replace (last-wins)
+    result[key] = value;
+  }
+
+  return result;
+}
+
+/**
+ * Merge multiple config layers in order (left to right, last wins).
+ *
+ * @param {...Object} layers - Configuration layers in priority order (lowest first)
+ * @returns {Object} Merged configuration
+ */
+function mergeAll(...layers) {
+  return layers.reduce((result, layer) => {
+    if (!layer || !isPlainObject(layer)) return result;
+    return deepMerge(result, layer);
+  }, {});
+}
+
+module.exports = {
+  deepMerge,
+  mergeAll,
+  isPlainObject,
+};

package/.grimoire/core/config/migrate-config.js

@@ -0,0 +1,293 @@
+/**
+ * Config Migration — Legacy core-config.yaml → L2 Project + L5 User
+ *
+ * Splits the monolithic core-config.yaml into:
+ *   - .grimoire/project-config.yaml (L2) — team-shared project settings
+ *   - ~/.grimoire/user-config.yaml (L5) — cross-project user preferences
+ *
+ * Safety:
+ * - Creates backup before migration (core-config.backup.yaml)
+ * - Idempotent: re-running does not duplicate or corrupt
+ * - Keeps core-config.yaml as legacy fallback (does not delete)
+ *
+ * @module core/config/migrate-config
+ * @version 1.0.0
+ * @created 2026-02-05 (Story 12.2)
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const yaml = require('js-yaml');
+
+/**
+ * Fields that belong in L5 User config (~/.grimoire/user-config.yaml).
+ * These are user-specific, cross-project preferences.
+ */
+const USER_FIELDS = [
+  'user_profile',
+  'default_model',
+  'default_language',
+  'coderabbit_integration',
+  'educational_mode',
+];
+
+/**
+ * Fields that belong in L2 Project config (.grimoire/project-config.yaml).
+ * These are project-specific, team-shared settings.
+ */
+const PROJECT_FIELDS = [
+  'project_name',
+  'project_type',
+  'environments',
+  'deploy_target',
+];
+
+/**
+ * Check if legacy core-config.yaml exists and framework-config.yaml does NOT.
+ *
+ * @param {string} projectRoot - Project root directory
+ * @returns {boolean} True if in legacy mode
+ */
+function isLegacyMode(projectRoot) {
+  const legacyPath = path.join(projectRoot, '.grimoire', 'core-config.yaml');
+  const frameworkPath = path.join(projectRoot, '.grimoire', 'framework-config.yaml');
+  return fs.existsSync(legacyPath) && !fs.existsSync(frameworkPath);
+}
+
+/**
+ * Create a backup of the legacy config file.
+ *
+ * @param {string} projectRoot - Project root directory
+ * @returns {string|null} Backup file path, or null if already backed up
+ */
+function createBackup(projectRoot) {
+  const legacyPath = path.join(projectRoot, '.grimoire', 'core-config.yaml');
+  const backupPath = path.join(projectRoot, '.grimoire', 'core-config.backup.yaml');
+
+  if (!fs.existsSync(legacyPath)) {
+    return null;
+  }
+
+  // Idempotent: skip if backup already exists
+  if (fs.existsSync(backupPath)) {
+    return backupPath;
+  }
+
+  fs.copyFileSync(legacyPath, backupPath);
+  return backupPath;
+}
+
+/**
+ * Extract user-level fields from legacy config.
+ *
+ * @param {Object} legacyConfig - Parsed legacy config
+ * @returns {Object} User config fields
+ */
+function extractUserFields(legacyConfig) {
+  const userConfig = {};
+
+  for (const field of USER_FIELDS) {
+    if (legacyConfig[field] !== undefined) {
+      userConfig[field] = legacyConfig[field];
+    }
+  }
+
+  // Default user_profile if not present
+  if (!userConfig.user_profile) {
+    userConfig.user_profile = 'advanced';
+  }
+
+  return userConfig;
+}
+
+/**
+ * Extract project-level fields from legacy config.
+ *
+ * @param {Object} legacyConfig - Parsed legacy config
+ * @returns {Object} Project config fields
+ */
+function extractProjectFields(legacyConfig) {
+  const projectConfig = {};
+
+  for (const field of PROJECT_FIELDS) {
+    if (legacyConfig[field] !== undefined) {
+      projectConfig[field] = legacyConfig[field];
+    }
+  }
+
+  // Extract from nested 'project' key if present
+  if (legacyConfig.project && typeof legacyConfig.project === 'object') {
+    if (legacyConfig.project.type && !projectConfig.project_type) {
+      projectConfig.project_type = legacyConfig.project.type;
+    }
+  }
+
+  return projectConfig;
+}
+
+/**
+ * Ensure the ~/.grimoire/ directory exists.
+ *
+ * @returns {string} Path to ~/.grimoire/ directory
+ */
+function ensureUserConfigDir() {
+  const dir = path.join(os.homedir(), '.grimoire');
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  }
+  return dir;
+}
+
+/**
+ * Write user config to ~/.grimoire/user-config.yaml.
+ * Merges with existing user config (does not overwrite existing fields).
+ *
+ * @param {Object} userFields - User config fields to write
+ * @returns {string} Path to user config file
+ */
+function writeUserConfig(userFields) {
+  ensureUserConfigDir();
+  const userConfigPath = path.join(os.homedir(), '.grimoire', 'user-config.yaml');
+
+  let existing = {};
+  try {
+    if (fs.existsSync(userConfigPath)) {
+      const content = fs.readFileSync(userConfigPath, 'utf8');
+      existing = yaml.load(content) || {};
+    }
+  } catch {
+    existing = {};
+  }
+
+  // Merge: existing values take precedence (don't overwrite user choices)
+  const merged = { ...userFields, ...existing };
+
+  const content = yaml.dump(merged, { lineWidth: -1 });
+  fs.writeFileSync(userConfigPath, content, 'utf8');
+
+  return userConfigPath;
+}
+
+/**
+ * Write project config to .grimoire/project-config.yaml.
+ * Merges with existing project config (does not overwrite existing fields).
+ *
+ * @param {string} projectRoot - Project root directory
+ * @param {Object} projectFields - Project config fields to write
+ * @returns {string} Path to project config file
+ */
+function writeProjectConfig(projectRoot, projectFields) {
+  const projectConfigPath = path.join(projectRoot, '.grimoire', 'project-config.yaml');
+
+  let existing = {};
+  try {
+    if (fs.existsSync(projectConfigPath)) {
+      const content = fs.readFileSync(projectConfigPath, 'utf8');
+      existing = yaml.load(content) || {};
+    }
+  } catch {
+    existing = {};
+  }
+
+  // Merge: existing values take precedence
+  const merged = { ...projectFields, ...existing };
+
+  // Only write if there are fields to write
+  if (Object.keys(merged).length === 0) {
+    return null;
+  }
+
+  const content = yaml.dump(merged, { lineWidth: -1 });
+  fs.writeFileSync(projectConfigPath, content, 'utf8');
+
+  return projectConfigPath;
+}
+
+/**
+ * Run the full migration from legacy core-config.yaml to layered config.
+ *
+ * @param {string} projectRoot - Project root directory
+ * @param {Object} [options] - Migration options
+ * @param {boolean} [options.dryRun] - If true, only report what would be done
+ * @returns {Object} Migration result
+ * @returns {boolean} result.migrated - Whether migration was performed
+ * @returns {string} [result.backupPath] - Path to backup file
+ * @returns {string} [result.userConfigPath] - Path to user config
+ * @returns {string} [result.projectConfigPath] - Path to project config
+ * @returns {string[]} result.warnings - Any warnings
+ * @returns {Object} [result.userFields] - Extracted user fields
+ * @returns {Object} [result.projectFields] - Extracted project fields
+ */
+function migrateConfig(projectRoot, options = {}) {
+  const result = {
+    migrated: false,
+    backupPath: null,
+    userConfigPath: null,
+    projectConfigPath: null,
+    warnings: [],
+    userFields: null,
+    projectFields: null,
+  };
+
+  const legacyPath = path.join(projectRoot, '.grimoire', 'core-config.yaml');
+
+  // Check if legacy config exists
+  if (!fs.existsSync(legacyPath)) {
+    result.warnings.push('No legacy core-config.yaml found. Nothing to migrate.');
+    return result;
+  }
+
+  // Parse legacy config
+  let legacyConfig;
+  try {
+    const content = fs.readFileSync(legacyPath, 'utf8');
+    legacyConfig = yaml.load(content) || {};
+  } catch (error) {
+    result.warnings.push(`Failed to parse core-config.yaml: ${error.message}`);
+    return result;
+  }
+
+  // Extract fields
+  const userFields = extractUserFields(legacyConfig);
+  const projectFields = extractProjectFields(legacyConfig);
+
+  result.userFields = userFields;
+  result.projectFields = projectFields;
+
+  if (options.dryRun) {
+    result.warnings.push('Dry run — no files written.');
+    return result;
+  }
+
+  // Create backup
+  result.backupPath = createBackup(projectRoot);
+
+  // Write user config (L5)
+  if (Object.keys(userFields).length > 0) {
+    result.userConfigPath = writeUserConfig(userFields);
+  }
+
+  // Write project config (L2)
+  if (Object.keys(projectFields).length > 0) {
+    result.projectConfigPath = writeProjectConfig(projectRoot, projectFields);
+  }
+
+  result.migrated = true;
+  return result;
+}
+
+module.exports = {
+  migrateConfig,
+  isLegacyMode,
+  createBackup,
+  extractUserFields,
+  extractProjectFields,
+  ensureUserConfigDir,
+  writeUserConfig,
+  writeProjectConfig,
+  USER_FIELDS,
+  PROJECT_FIELDS,
+};
+
+

package/.grimoire/core/config/schemas/framework-config.schema.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "framework-config.schema.json",
+  "title": "grimoire Framework Configuration (L1)",
+  "description": "Read-only framework defaults shipped with the npm package",
+  "type": "object",
+  "properties": {
+    "version": {
+      "type": "string",
+      "description": "Framework version"
+    },
+    "framework_name": {
+      "type": "string",
+      "description": "Framework name"
+    }
+  },
+  "additionalProperties": true
+}
+

package/.grimoire/core/config/schemas/local-config.schema.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "local-config.schema.json",
+  "title": "grimoire Local Configuration (L4)",
+  "description": "Machine-specific settings stored in .grimoire/local-config.yaml (gitignored)",
+  "type": "object",
+  "properties": {
+    "ide": {
+      "type": "object",
+      "description": "IDE-specific overrides"
+    },
+    "mcp": {
+      "type": "object",
+      "description": "MCP server local overrides"
+    }
+  },
+  "additionalProperties": true
+}
+
+

package/.grimoire/core/config/schemas/project-config.schema.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "project-config.schema.json",
+  "title": "grimoire Project Configuration (L2)",
+  "description": "Team-shared project settings stored in .grimoire/project-config.yaml",
+  "type": "object",
+  "properties": {
+    "project_name": {
+      "type": "string",
+      "description": "Project name"
+    },
+    "project_type": {
+      "type": "string",
+      "enum": ["fullstack", "api", "frontend", "library", "cli"],
+      "description": "Project type"
+    },
+    "environments": {
+      "type": "object",
+      "description": "Environment-specific configurations",
+      "additionalProperties": {
+        "type": "object"
+      }
+    },
+    "deploy_target": {
+      "type": "string",
+      "description": "Deployment target platform"
+    }
+  },
+  "additionalProperties": true
+}
+
+

package/.grimoire/core/config/schemas/user-config.schema.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "user-config.schema.json",
+  "title": "grimoire User Configuration (L5)",
+  "description": "Cross-project user preferences stored in ~/.grimoire/user-config.yaml",
+  "type": "object",
+  "required": ["user_profile"],
+  "properties": {
+    "user_profile": {
+      "type": "string",
+      "enum": ["bob", "advanced"],
+      "description": "User interface mode"
+    },
+    "default_model": {
+      "type": "string",
+      "description": "Default AI model for agent operations"
+    },
+    "default_language": {
+      "type": "string",
+      "description": "Default language for agent responses"
+    },
+    "educational_mode": {
+      "type": "boolean",
+      "description": "Enable detailed explanations of actions"
+    },
+    "coderabbit_integration": {
+      "type": "boolean",
+      "description": "Enable CodeRabbit automated review"
+    }
+  },
+  "additionalProperties": true
+}
+

package/.grimoire/core/config/templates/user-config.yaml

@@ -0,0 +1,24 @@
+# ============================================
+# grimoire User Configuration (L5)
+# Location: ~/.grimoire/user-config.yaml
+# Scope: Cross-project, per-user preferences
+# Priority: Highest (overrides L1-L4)
+# ============================================
+
+# User profile mode (REQUIRED)
+# - bob: Simplified mode — only Bob visible, orchestrates internally
+# - advanced: Full access to all agents and commands
+user_profile: "bob"
+
+# Default AI model for agent operations
+default_model: "claude-sonnet"
+
+# Default language for agent responses
+default_language: "pt-BR"
+
+# CodeRabbit automated review integration
+coderabbit_integration: true
+
+# Educational mode — provides detailed explanations of actions
+educational_mode: false
+