@craftpipe/contextpack 1.0.0

package/lib/premium/config-file.js

@@ -0,0 +1,917 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { requirePro } = require('../premium/gate');
+const { loadConfig, mergeWithFlags } = require('../config');
+
+/**
+ * Supported config file names in order of precedence
+ */
+const CONFIG_FILE_NAMES = [
+  '.contextpackrc.json',
+  '.contextpackrc.js',
+  '.contextpackrc.cjs',
+  'contextpack.config.json',
+  'contextpack.config.js',
+  'contextpack.config.cjs',
+];
+
+/**
+ * Package.json key for embedded config
+ */
+const PACKAGE_JSON_KEY = 'contextpack';
+
+/**
+ * Deep merge two objects, with source overriding target
+ * @param {object} target
+ * @param {object} source
+ * @returns {object}
+ */
+function deepMerge(target, source) {
+  if (!source || typeof source !== 'object') return target;
+  if (!target || typeof target !== 'object') return source;
+
+  const result = Object.assign({}, target);
+
+  for (const key of Object.keys(source)) {
+    const srcVal = source[key];
+    const tgtVal = result[key];
+
+    if (
+      srcVal !== null &&
+      typeof srcVal === 'object' &&
+      !Array.isArray(srcVal) &&
+      tgtVal !== null &&
+      typeof tgtVal === 'object' &&
+      !Array.isArray(tgtVal)
+    ) {
+      result[key] = deepMerge(tgtVal, srcVal);
+    } else {
+      result[key] = srcVal;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Validate a config object for required types and known fields
+ * @param {object} config
+ * @returns {{ valid: boolean, errors: string[], warnings: string[] }}
+ */
+function validateConfigShape(config) {
+  const errors = [];
+  const warnings = [];
+
+  if (config === null || typeof config !== 'object' || Array.isArray(config)) {
+    errors.push('Config must be a plain object.');
+    return { valid: false, errors, warnings };
+  }
+
+  const stringFields = ['rootDir', 'output', 'format'];
+  for (const field of stringFields) {
+    if (field in config && typeof config[field] !== 'string') {
+      errors.push(`Field "${field}" must be a string, got ${typeof config[field]}.`);
+    }
+  }
+
+  const numberFields = ['tokenLimit', 'maxFileSummaryLength'];
+  for (const field of numberFields) {
+    if (field in config) {
+      if (typeof config[field] !== 'number' || !isFinite(config[field])) {
+        errors.push(`Field "${field}" must be a finite number, got ${typeof config[field]}.`);
+      } else if (config[field] < 0) {
+        errors.push(`Field "${field}" must be non-negative.`);
+      }
+    }
+  }
+
+  const boolFields = ['verbose', 'includeDependencyMap', 'includeSymbolIndex'];
+  for (const field of boolFields) {
+    if (field in config && typeof config[field] !== 'boolean') {
+      warnings.push(`Field "${field}" should be a boolean, got ${typeof config[field]}.`);
+    }
+  }
+
+  const arrayFields = ['include', 'exclude'];
+  for (const field of arrayFields) {
+    if (field in config) {
+      if (!Array.isArray(config[field])) {
+        errors.push(`Field "${field}" must be an array.`);
+      } else {
+        for (let i = 0; i < config[field].length; i++) {
+          if (typeof config[field][i] !== 'string') {
+            errors.push(`Field "${field}[${i}]" must be a string.`);
+          }
+        }
+      }
+    }
+  }
+
+  if ('format' in config && typeof config.format === 'string') {
+    const validFormats = ['json', 'markdown', 'md'];
+    if (!validFormats.includes(config.format.toLowerCase())) {
+      warnings.push(
+        `Field "format" has unrecognized value "${config.format}". Expected one of: ${validFormats.join(', ')}.`
+      );
+    }
+  }
+
+  if ('fileTypes' in config && config.fileTypes !== null && typeof config.fileTypes === 'object') {
+    const ft = config.fileTypes;
+    if ('extensions' in ft && !Array.isArray(ft.extensions)) {
+      errors.push('Field "fileTypes.extensions" must be an array.');
+    }
+    if ('excludeExtensions' in ft && !Array.isArray(ft.excludeExtensions)) {
+      errors.push('Field "fileTypes.excludeExtensions" must be an array.');
+    }
+  }
+
+  if (
+    'symbolExtraction' in config &&
+    config.symbolExtraction !== null &&
+    typeof config.symbolExtraction === 'object'
+  ) {
+    const se = config.symbolExtraction;
+    const seBools = [
+      'enabled',
+      'extractFunctions',
+      'extractClasses',
+      'extractExports',
+      'extractImports',
+      'extractArrowFunctions',
+      'extractDefaultExports',
+      'excludePrivate',
+    ];
+    for (const field of seBools) {
+      if (field in se && typeof se[field] !== 'boolean') {
+        warnings.push(`Field "symbolExtraction.${field}" should be a boolean.`);
+      }
+    }
+    if ('minSymbolLength' in se) {
+      if (typeof se.minSymbolLength !== 'number' || !isFinite(se.minSymbolLength)) {
+        errors.push('Field "symbolExtraction.minSymbolLength" must be a number.');
+      } else if (se.minSymbolLength < 1) {
+        errors.push('Field "symbolExtraction.minSymbolLength" must be at least 1.');
+      }
+    }
+    if ('languages' in se && !Array.isArray(se.languages)) {
+      errors.push('Field "symbolExtraction.languages" must be an array.');
+    }
+    if ('excludePatterns' in se && !Array.isArray(se.excludePatterns)) {
+      errors.push('Field "symbolExtraction.excludePatterns" must be an array.');
+    }
+  }
+
+  if ('directoryRules' in config) {
+    if (!Array.isArray(config.directoryRules)) {
+      errors.push('Field "directoryRules" must be an array.');
+    } else {
+      for (let i = 0; i < config.directoryRules.length; i++) {
+        const rule = config.directoryRules[i];
+        if (!rule || typeof rule !== 'object') {
+          errors.push(`Field "directoryRules[${i}]" must be an object.`);
+          continue;
+        }
+        if (!('directory' in rule)) {
+          warnings.push(`Field "directoryRules[${i}]" is missing "directory" key.`);
+        } else if (typeof rule.directory !== 'string') {
+          errors.push(`Field "directoryRules[${i}].directory" must be a string.`);
+        }
+        if ('include' in rule && !Array.isArray(rule.include)) {
+          errors.push(`Field "directoryRules[${i}].include" must be an array.`);
+        }
+        if ('exclude' in rule && !Array.isArray(rule.exclude)) {
+          errors.push(`Field "directoryRules[${i}].exclude" must be an array.`);
+        }
+      }
+    }
+  }
+
+  if ('profiles' in config) {
+    if (!Array.isArray(config.profiles)) {
+      errors.push('Field "profiles" must be an array.');
+    } else {
+      for (let i = 0; i < config.profiles.length; i++) {
+        const profile = config.profiles[i];
+        if (!profile || typeof profile !== 'object') {
+          errors.push(`Field "profiles[${i}]" must be an object.`);
+          continue;
+        }
+        if (!('name' in profile) || typeof profile.name !== 'string') {
+          errors.push(`Field "profiles[${i}].name" must be a string.`);
+        }
+      }
+    }
+  }
+
+  return { valid: errors.length === 0, errors, warnings };
+}
+
+/**
+ * Locate a config file by searching upward from startDir
+ * @param {string} startDir - Directory to begin search
+ * @param {number} maxDepth - Maximum number of parent directories to traverse
+ * @returns {{ filePath: string, fileName: string } | null}
+ */
+function findConfigFile(startDir, maxDepth) {
+  const opts = { startDir, maxDepth };
+  const { startDir: start = process.cwd(), maxDepth: depth = 5 } = opts || {};
+
+  let current = path.resolve(start);
+  let traversed = 0;
+
+  while (traversed <= depth) {
+    for (const name of CONFIG_FILE_NAMES) {
+      const candidate = path.join(current, name);
+      if (fs.existsSync(candidate)) {
+        return { filePath: candidate, fileName: name };
+      }
+    }
+
+    const pkgPath = path.join(current, 'package.json');
+    if (fs.existsSync(pkgPath)) {
+      try {
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+        if (pkg && typeof pkg === 'object' && PACKAGE_JSON_KEY in pkg) {
+          return { filePath: pkgPath, fileName: 'package.json', embeddedKey: PACKAGE_JSON_KEY };
+        }
+      } catch (_) {
+        // ignore malformed package.json during discovery
+      }
+    }
+
+    const parent = path.dirname(current);
+    if (parent === current) break;
+    current = parent;
+    traversed++;
+  }
+
+  return null;
+}
+
+/**
+ * Load raw config data from a file path
+ * @param {string} filePath - Absolute path to config file
+ * @param {string|undefined} embeddedKey - If set, read this key from the parsed object
+ * @returns {object}
+ */
+function loadRawConfig(filePath, embeddedKey) {
+  const ext = path.extname(filePath).toLowerCase();
+
+  let raw;
+
+  if (ext === '.json') {
+    let content;
+    try {
+      content = fs.readFileSync(filePath, 'utf8');
+    } catch (err) {
+      throw new Error(`Cannot read config file "${filePath}": ${err.message}`);
+    }
+
+    // Strip single-line comments before parsing (common in .contextpackrc.json)
+    const stripped = content.replace(/^\s*\/\/.*$/gm, '').replace(/,\s*([\]}])/g, '$1');
+
+    try {
+      raw = JSON.parse(stripped);
+    } catch (err) {
+      throw new Error(`Cannot parse JSON in "${filePath}": ${err.message}`);
+    }
+  } else if (ext === '.js' || ext === '.cjs') {
+    try {
+      // Clear require cache so edits are picked up in watch scenarios
+      delete require.cache[require.resolve(filePath)];
+      raw = require(filePath);
+    } catch (err) {
+      throw new Error(`Cannot load JS config file "${filePath}": ${err.message}`);
+    }
+  } else {
+    throw new Error(`Unsupported config file extension "${ext}" for file "${filePath}".`);
+  }
+
+  if (embeddedKey) {
+    if (!raw || typeof raw !== 'object' || !(embeddedKey in raw)) {
+      throw new Error(
+        `Expected key "${embeddedKey}" in "${filePath}" but it was not found.`
+      );
+    }
+    raw = raw[embeddedKey];
+  }
+
+  // Strip internal comment keys before returning
+  if (raw && typeof raw === 'object' && !Array.isArray(raw)) {
+    raw = stripCommentKeys(raw);
+  }
+
+  return raw;
+}
+
+/**
+ * Recursively remove keys starting with "_comment" from a config object
+ * @param {object} obj
+ * @returns {object}
+ */
+function stripCommentKeys(obj) {
+  if (!obj || typeof obj !== 'object') return obj;
+  if (Array.isArray(obj)) return obj.map(stripCommentKeys);
+
+  const result = {};
+  for (const key of Object.keys(obj)) {
+    if (key.startsWith('_comment')) continue;
+    result[key] = stripCommentKeys(obj[key]);
+  }
+  return result;
+}
+
+/**
+ * Resolve a named profile from a config object
+ * @param {object} config - Full config object
+ * @param {string} profileName - Name of the profile to resolve
+ * @returns {object} - Merged config with profile applied on top
+ */
+function resolveProfile(config, profileName) {
+  const { profiles } = config || {};
+
+  if (!Array.isArray(profiles) || profiles.length === 0) {
+    throw new Error(
+      `Profile "${profileName}" requested but no "profiles" array found in config.`
+    );
+  }
+
+  const profile = profiles.find(
+    (p) => p && typeof p === 'object' && p.name === profileName
+  );
+
+  if (!profile) {
+    const available = profiles
+      .filter((p) => p && typeof p.name === 'string')
+      .map((p) => `"${p.name}"`)
+      .join(', ');
+    throw new Error(
+      `Profile "${profileName}" not found. Available profiles: ${available || 'none'}.`
+    );
+  }
+
+  // Clone profile without the name key, then deep merge onto base config
+  const { name: _name, ...profileOverrides } = profile;
+  const base = Object.assign({}, config);
+  delete base.profiles;
+
+  return deepMerge(base, profileOverrides);
+}
+
+/**
+ * Write a config file to disk
+ * @param {string} filePath - Destination path
+ * @param {object} config - Config object to write
+ * @param {{ format?: 'json'|'js', pretty?: boolean }} opts
+ */
+function writeConfigFile(filePath, config, opts) {
+  const { format = 'json', pretty = true } = opts || {};
+
+  let content;
+
+  if (format === 'js' || filePath.endsWith('.js') || filePath.endsWith('.cjs')) {
+    const serialized = JSON.stringify(config, null, pretty ? 2 : 0);
+    content = `'use strict';\n\nmodule.exports = ${serialized};\n`;
+  } else {
+    content = JSON.stringify(config, null, pretty ? 2 : 0);
+  }
+
+  try {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, content, 'utf8');
+  } catch (err) {
+    throw new Error(`Cannot write config file "${filePath}": ${err.message}`);
+  }
+}
+
+/**
+ * Generate a default config scaffold with all documented fields
+ * @param {object} overrides - Optional field overrides
+ * @returns {object}
+ */
+function generateDefaultConfig(overrides) {
+  const base = {
+    rootDir: '.',
+    include: ['**/*'],
+    exclude: [
+      'node_modules/**',
+      '.git/**',
+      'dist/**',
+      'build/**',
+      'coverage/**',
+      '.nyc_output/**',
+      '**/*.min.js',
+      '**/*.map',
+      '**/*.lock',
+      '**/*.log',
+      'tmp/**',
+      '.cache/**',
+    ],
+    fileTypes: {
+      extensions: [
+        '.js', '.mjs', '.cjs', '.jsx',
+        '.ts', '.tsx',
+        '.json', '.md',
+        '.py', '.rb', '.go', '.java', '.cs', '.php', '.swift', '.kt',
+      ],
+      excludeExtensions: [
+        '.png', '.jpg', '.jpeg', '.gif', '.svg', '.ico',
+        '.woff', '.woff2', '.ttf', '.eot',
+        '.mp4', '.mp3', '.zip', '.tar', '.gz',
+      ],
+    },
+    output: 'contextpack-output.json',
+    format: 'json',
+    tokenLimit: 100000,
+    maxFileSummaryLength: 500,
+    includeDependencyMap: true,
+    includeSymbolIndex: true,
+    verbose: false,
+    symbolExtraction: {
+      enabled: true,
+      extractFunctions: true,
+      extractClasses: true,
+      extractExports: true,
+      extractImports: true,
+      extractArrowFunctions: true,
+      extractDefaultExports: true,
+      languages: ['javascript', 'typescript'],
+      minSymbolLength: 2,
+      excludePrivate: false,
+      excludePatterns: ['^_', '^test', '^spec', '^mock'],
+    },
+    directoryRules: [],
+    profiles: [],
+  };
+
+  return deepMerge(base, overrides || {});
+}
+
+/**
+ * Diff two config objects and return a structured change report
+ * @param {object} baseConfig
+ * @param {object} newConfig
+ * @param {string} [keyPath]
+ * @returns {Array<{ path: string, type: 'added'|'removed'|'changed', from: any, to: any }>}
+ */
+function diffConfigs(baseConfig, newConfig, keyPath) {
+  const prefix = keyPath ? keyPath + '.' : '';
+  const changes = [];
+
+  const allKeys = new Set([
+    ...Object.keys(baseConfig || {}),
+    ...Object.keys(newConfig || {}),
+  ]);
+
+  for (const key of allKeys) {
+    if (key.startsWith('_comment')) continue;
+
+    const fullKey = prefix + key;
+    const baseVal = (baseConfig || {})[key];
+    const newVal = (newConfig || {})[key];
+
+    if (!(key in (baseConfig || {}))) {
+      changes.push({ path: fullKey, type: 'added', from: undefined, to: newVal });
+    } else if (!(key in (newConfig || {}))) {
+      changes.push({ path: fullKey, type: 'removed', from: baseVal, to: undefined });
+    } else if (
+      baseVal !== null &&
+      typeof baseVal === 'object' &&
+      !Array.isArray(baseVal) &&
+      newVal !== null &&
+      typeof newVal === 'object' &&
+      !Array.isArray(newVal)
+    ) {
+      const nested = diffConfigs(baseVal, newVal, fullKey);
+      changes.push(...nested);
+    } else if (JSON.stringify(baseVal) !== JSON.stringify(newVal)) {
+      changes.push({ path: fullKey, type: 'changed', from: baseVal, to: newVal });
+    }
+  }
+
+  return changes;
+}
+
+/**
+ * Format a diff report as a human-readable string
+ * @param {Array} changes
+ * @returns {string}
+ */
+function formatDiff(changes) {
+  if (!Array.isArray(changes) || changes.length === 0) {
+    return 'No differences found.';
+  }
+
+  const lines = [];
+
+  for (const change of changes) {
+    if (change.type === 'added') {
+      lines.push(`  + ${change.path}: ${JSON.stringify(change.to)}`);
+    } else if (change.type === 'removed') {
+      lines.push(`  - ${change.path}: ${JSON.stringify(change.from)}`);
+    } else if (change.type === 'changed') {
+      lines.push(
+        `  ~ ${change.path}: ${JSON.stringify(change.from)} → ${JSON.stringify(change.to)}`
+      );
+    }
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Merge multiple config files in order, with later files taking precedence
+ * @param {string[]} filePaths - Ordered list of config file paths
+ * @param {object} [cliFlags] - CLI flags to apply last
+ * @returns {{ config: object, sources: string[] }}
+ */
+function mergeConfigFiles(filePaths, cliFlags) {
+  const paths = Array.isArray(filePaths) ? filePaths : [];
+  const sources = [];
+  let merged = generateDefaultConfig();
+
+  for (const filePath of paths) {
+    if (!filePath || typeof filePath !== 'string') continue;
+
+    const resolved = path.resolve(filePath);
+
+    if (!fs.existsSync(resolved)) {
+      throw new Error(`Config file not found: "${resolved}"`);
+    }
+
+    const raw = loadRawConfig(resolved, undefined);
+    merged = deepMerge(merged, raw);
+    sources.push(resolved);
+  }
+
+  if (cliFlags && typeof cliFlags === 'object') {
+    merged = mergeWithFlags(merged, cliFlags);
+  }
+
+  return { config: merged, sources };
+}
+
+/**
+ * Main entry point for the config-file premium feature
+ *
+ * Supported actions:
+ *   - 'find'     : Locate the config file from a given directory
+ *   - 'load'     : Load, validate, and return the resolved config
+ *   - 'validate' : Validate a config file and return a report
+ *   - 'init'     : Scaffold a new config file at a given path
+ *   - 'profile'  : Load config and apply a named profile
+ *   - 'diff'     : Compare two config files and report differences
+ *   - 'merge'    : Merge multiple config files into one resolved config
+ *   - 'show'     : Pretty-print the resolved config to stdout
+ *
+ * @param {object} opts
+ * @param {string} [opts.action='load']
+ * @param {string} [opts.cwd] - Working directory for file discovery
+ * @param {string} [opts.configPath] - Explicit config file path
+ * @param {string} [opts.profileName] - Profile name to activate
+ * @param {string} [opts.outputPath] - Destination for 'init' action
+ * @param {string} [opts.compareWith] - Second config path for 'diff' action
+ * @param {string[]} [opts.mergeFiles] - Ordered config paths for 'merge' action
+ * @param {object} [opts.cliFlags] - CLI flags to merge last
+ * @param {boolean} [opts.strict] - Treat validation warnings as errors
+ * @param {boolean} [opts.verbose] - Print extra diagnostic info
+ * @param {number} [opts.maxSearchDepth] - Max parent dirs to search (default 5)
+ * @returns {object} - Result object with action-specific fields
+ */
+function configFile(opts) {
+  requirePro('Config File Management');
+
+  const {
+    action = 'load',
+    cwd = process.cwd(),
+    configPath,
+    profileName,
+    outputPath,
+    compareWith,
+    mergeFiles,
+    cliFlags,
+    strict = false,
+    verbose = false,
+    maxSearchDepth = 5,
+  } = opts || {};
+
+  const log = verbose
+    ? (...args) => console.log('[config-file]', ...args)
+    : () => {};
+
+  // ── FIND ──────────────────────────────────────────────────────────────────
+  if (action === 'find') {
+    log('Searching for config file from:', cwd);
+
+    const found = findConfigFile(cwd, maxSearchDepth);
+
+    if (!found) {
+      return {
+        action,
+        found: false,
+        filePath: null,
+        fileName: null,
+        message: 'No config file found.',
+      };
+    }
+
+    log('Found config file:', found.filePath);
+
+    return {
+      action,
+      found: true,
+      filePath: found.filePath,
+      fileName: found.fileName,
+      embeddedKey: found.embeddedKey || null,
+      message: `Config file found: ${found.filePath}`,
+    };
+  }
+
+  // ── VALIDATE ──────────────────────────────────────────────────────────────
+  if (action === 'validate') {
+    const targetPath = configPath
+      ? path.resolve(configPath)
+      : (() => {
+          const found = findConfigFile(cwd, maxSearchDepth);
+          if (!found) throw new Error('No config file found to validate.');
+          return found.filePath;
+        })();
+
+    log('Validating config file:', targetPath);
+
+    let raw;
+    try {
+      raw = loadRawConfig(targetPath, undefined);
+    } catch (err) {
+      return {
+        action,
+        valid: false,
+        filePath: targetPath,
+        errors: [err.message],
+        warnings: [],
+        message: `Validation failed: ${err.message}`,
+      };
+    }
+
+    const report = validateConfigShape(raw);
+
+    if (strict && report.warnings.length > 0) {
+      report.errors.push(...report.warnings.map((w) => `[strict] ${w}`));
+      report.warnings = [];
+      report.valid = false;
+    }
+
+    log('Validation result:', report.valid ? 'PASS' : 'FAIL');
+
+    return {
+      action,
+      valid: report.valid,
+      filePath: targetPath,
+      errors: report.errors,
+      warnings: report.warnings,
+      message: report.valid
+        ? `Config file is valid: ${targetPath}`
+        : `Config file has ${report.errors.length} error(s).`,
+    };
+  }
+
+  // ── INIT ──────────────────────────────────────────────────────────────────
+  if (action === 'init') {
+    const dest = outputPath
+      ? path.resolve(outputPath)
+      : path.join(path.resolve(cwd), '.contextpackrc.json');
+
+    if (fs.existsSync(dest)) {
+      throw new Error(
+        `Config file already exists at "${dest}". Delete it first or specify a different --output-path.`
+      );
+    }
+
+    log('Scaffolding config file at:', dest);
+
+    const defaultConfig = generateDefaultConfig(cliFlags || {});
+    writeConfigFile(dest, defaultConfig, { format: 'json', pretty: true });
+
+    return {
+      action,
+      filePath: dest,
+      config: defaultConfig,
+      message: `Config file created: ${dest}`,
+    };
+  }
+
+  // ── DIFF ──────────────────────────────────────────────────────────────────
+  if (action === 'diff') {
+    if (!configPath) {
+      throw new Error('action "diff" requires opts.configPath (base config).');
+    }
+    if (!compareWith) {
+      throw new Error('action "diff" requires opts.compareWith (second config path).');
+    }
+
+    const basePath = path.resolve(configPath);
+    const comparePath = path.resolve(compareWith);
+
+    log('Diffing configs:', basePath, '↔', comparePath);
+
+    const baseRaw = loadRawConfig(basePath, undefined);
+    const compareRaw = loadRawConfig(comparePath, undefined);
+
+    const changes = diffConfigs(baseRaw, compareRaw);
+    const formatted = formatDiff(changes);
+
+    return {
+      action,
+      baseFile: basePath,
+      compareFile: comparePath,
+      changes,
+      changeCount: changes.length,
+      formatted,
+      message:
+        changes.length === 0
+          ? 'Configs are identical.'
+          : `Found ${changes.length} difference(s).`,
+    };
+  }
+
+  // ── MERGE ─────────────────────────────────────────────────────────────────
+  if (action === 'merge') {
+    const files = Array.isArray(mergeFiles) && mergeFiles.length > 0
+      ? mergeFiles
+      : (() => {
+          if (!configPath) {
+            throw new Error(
+              'action "merge" requires opts.mergeFiles (array) or opts.configPath.'
+            );
+          }
+          return [configPath];
+        })();
+
+    log('Merging config files:', files);
+
+    const { config: merged, sources } = mergeConfigFiles(files, cliFlags);
+    const report = validateConfigShape(merged);
+
+    if (outputPath) {
+      const dest = path.resolve(outputPath);
+      writeConfigFile(dest, merged, { format: 'json', pretty: true });
+      log('Merged config written to:', dest);
+    }
+
+    return {
+      action,
+      config: merged,
+      sources,
+      valid: report.valid,
+      errors: report.errors,
+      warnings: report.warnings,
+      outputPath: outputPath ? path.resolve(outputPath) : null,
+      message: `Merged ${sources.length} config file(s).`,
+    };
+  }
+
+  // ── PROFILE ───────────────────────────────────────────────────────────────
+  if (action === 'profile') {
+    if (!profileName) {
+      throw new Error('action "profile" requires opts.profileName.');
+    }
+
+    const targetPath = configPath
+      ? path.resolve(configPath)
+      : (() => {
+          const found = findConfigFile(cwd, maxSearchDepth);
+          if (!found) throw new Error('No config file found for profile resolution.');
+          return found.filePath;
+        })();
+
+    log('Loading config for profile:', profileName, 'from:', targetPath);
+
+    const raw = loadRawConfig(targetPath, undefined);
+    const resolved = resolveProfile(raw, profileName);
+
+    if (cliFlags && typeof cliFlags === 'object') {
+      Object.assign(resolved, mergeWithFlags(resolved, cliFlags));
+    }
+
+    const report = validateConfigShape(resolved);
+
+    return {
+      action,
+      profileName,
+      filePath: targetPath,
+      config: resolved,
+      valid: report.valid,
+      errors: report.errors,
+      warnings: report.warnings,
+      message: `Profile "${profileName}" resolved from "${targetPath}".`,
+    };
+  }
+
+  // ── SHOW ──────────────────────────────────────────────────────────────────
+  if (action === 'show') {
+    const targetPath = configPath
+      ? path.resolve(configPath)
+      : (() => {
+          const found = findConfigFile(cwd, maxSearchDepth);
+          if (!found) throw new Error('No config file found to show.');
+          return found.filePath;
+        })();
+
+    log('Showing config from:', targetPath);
+
+    const raw = loadRawConfig(targetPath, undefined);
+    let resolved = raw;
+
+    if (cliFlags && typeof cliFlags === 'object') {
+      resolved = mergeWithFlags(raw, cliFlags);
+    }
+
+    const report = validateConfigShape(resolved);
+
+    console.log('\n── ContextPack Config ──────────────────────────────');
+    console.log('  File:', targetPath);
+    console.log('  Valid:', report.valid ? '✓ Yes' : '✗ No');
+    if (report.errors.length > 0) {
+      console.log('  Errors:');
+      report.errors.forEach((e) => console.log('    ✗', e));
+    }
+    if (report.warnings.length > 0) {
+      console.log('  Warnings:');
+      report.warnings.forEach((w) => console.log('    ⚠', w));
+    }
+    console.log('────────────────────────────────────────────────────');
+    console.log(JSON.stringify(resolved, null, 2));
+    console.log('────────────────────────────────────────────────────\n');
+
+    return {
+      action,
+      filePath: targetPath,
+      config: resolved,
+      valid: report.valid,
+      errors: report.errors,
+      warnings: report.warnings,
+      message: `Config shown from "${targetPath}".`,
+    };
+  }
+
+  // ── LOAD (default) ────────────────────────────────────────────────────────
+  {
+    const targetPath = configPath
+      ? path.resolve(configPath)
+      : (() => {
+          const found = findConfigFile(cwd, maxSearchDepth);
+          if (!found) {
+            log('No config file found; using defaults.');
+            return null;
+          }
+          return found.filePath;
+        })();
+
+    let raw;
+
+    if (targetPath) {
+      log('Loading config from:', targetPath);
+      raw = loadRawConfig(targetPath, undefined);
+    } else {
+      raw = generateDefaultConfig();
+    }
+
+    let resolved = raw;
+
+    if (profileName) {
+      log('Applying profile:', profileName);
+      resolved = resolveProfile(raw, profileName);
+    }
+
+    if (cliFlags && typeof cliFlags === 'object') {
+      resolved = mergeWithFlags(resolved, cliFlags);
+    }
+
+    const report = validateConfigShape(resolved);
+
+    if (strict && !report.valid) {
+      const summary = report.errors.join('; ');
+      throw new Error(`Config validation failed (strict mode): ${summary}`);
+    }
+
+    log('Config loaded successfully. Valid:', report.valid);
+
+    return {
+      action: 'load',
+      filePath: targetPath,
+      config: resolved,
+      valid: report.valid,
+      errors: report.errors,
+      warnings: report.warnings,
+      usingDefaults: !targetPath,
+      message: targetPath
+        ? `Config loaded from "${targetPath}".`
+        : 'No config file found; using built-in defaults.',
+    };
+  }
+}
+
+module.exports = { configFile };