YAML File Merger CLI

Common errors

• command not found: merge-yaml

  cause The `merge-yaml-cli` package was installed locally or not installed at all, rather than globally.
  fix Install the package globally using `npm install -g merge-yaml-cli` or `yarn global add merge-yaml-cli`. Alternatively, if installed locally, run it via `npx merge-yaml-cli` or by adding it to your `package.json` scripts.

• Error: ENOENT: no such file or directory, open 'nonexistent.yml'

  cause One or more of the input YAML files specified in the command-line arguments or API call does not exist at the given path.
  fix Verify that all file paths and glob patterns are correct and that the files exist relative to the current working directory or as absolute paths. Double-check for typos in file names or directories.

• YAMLException: bad indentation of a mapping entry at line X, column Y

  cause One of the input YAML files contains invalid YAML syntax, specifically an indentation error.
  fix Review the indicated YAML file (and line/column number if provided) for incorrect indentation. YAML is very sensitive to whitespace for defining structure. Use a YAML linter or validator to identify and fix syntax errors.

Warnings

• gotcha The project's npm page indicates the last publish was 8 years ago, suggesting the package is not actively maintained. This could lead to unaddressed bugs or compatibility issues with newer Node.js versions or YAML specifications. Consider checking GitHub for more recent activity or forks.
  Fix: Evaluate alternative, more actively maintained YAML merging tools for production environments or critical projects. If using `merge-yaml-cli`, thoroughly test its behavior in your specific environment and Node.js version.
• breaking The package uses `glob` for file pattern matching. Changes in `glob`'s behavior or updates to Node.js's file system APIs could potentially alter how file paths are resolved or matched, leading to unexpected merge inputs or outputs. No specific breaking changes are documented for `merge-yaml-cli` itself between versions in the provided context, but `glob` updates could cause subtle issues.
  Fix: Always test glob patterns thoroughly, especially after Node.js runtime upgrades. Consider explicit file lists if glob behavior becomes unpredictable for critical merges.
• gotcha The `merge-yaml-cli` tool performs a simple deep merge, where later files in the input list will overwrite conflicting keys from earlier files. It does not specify advanced merging strategies like array concatenation, which might be desired for certain configurations. For example, if both files define an array for the same key, the array from the later file will replace the earlier one, not combine them.
  Fix: Understand the merging logic (last-in wins for conflicting keys). If array concatenation or other sophisticated merge strategies are required, consider pre-processing your YAML files or using a different tool (e.g., `yq` or `combine-yaml-cli`) that supports these specific behaviors.
• gotcha Security vulnerabilities in YAML parsing libraries (like `js-yaml`, which this package likely uses) are a known risk, especially when processing untrusted input. Exploits can include arbitrary code execution through unsafe loading of YAML documents. While the Snyk badge indicates known vulnerabilities for the project, the specific details aren't provided in the excerpt.
  Fix: Avoid using `merge-yaml-cli` to process YAML files from untrusted sources. Regularly check the project's Snyk report or similar vulnerability scanners for updates on its dependencies. For programmatic usage, ensure no unsafe `yaml.load` equivalents are exposed or used internally without proper sanitization if user input is involved.

Install

• npm install merge-yaml-cli npm
• yarn add merge-yaml-cli yarn
• pnpm add merge-yaml-cli pnpm

Imports

• mergeYaml
  wrong:

  import mergeYaml from 'merge-yaml-cli'

  correct:

  const mergeYaml = require('merge-yaml-cli')

  This package is CommonJS-only. Direct ESM 'import' syntax is not supported and will result in an error. The `require()` call provides the main API object.
• mergeYaml.merge
  wrong:

  import { merge } from 'merge-yaml-cli'

  correct:

  const mergeYaml = require('merge-yaml-cli');
  const result = mergeYaml.merge(['file1.yml', 'file2.yml'])

  The `merge` function is a method on the default CommonJS export. It's not a named export for ESM. Ensure you destructure from the `require`d object if you wish to use it directly.
• mergeYaml.on
  wrong:

  mergeYaml.addEventListener('files', ...)

  correct:

  const mergeYaml = require('merge-yaml-cli');
  mergeYaml.on('files', (files) => console.log('Files found:', files))

  The `mergeYaml` object acts as an `EventEmitter` for progress or information. Use the Node.js `on` method, not browser-style `addEventListener`.

Quickstart

Demonstrates global installation and usage of the `merge-yaml-cli` command-line utility to merge multiple YAML files using glob patterns and output the result.

#!/usr/bin/env node

// Create dummy YAML files for demonstration
const fs = require('fs');
fs.writeFileSync('config/base.yml', 'name: MyApp\nversion: 1.0.0\nenvironment: development');
fs.writeFileSync('config/overrides/prod.yml', 'environment: production\nscale: large\nfeatures:\n  - analytics\n  - monitoring');
fs.writeFileSync('config/overrides/test.yml', 'environment: testing\nscale: medium\nfeatures:\n  - logging');

console.log('Dummy YAML files created.');
console.log('Running merge-yaml-cli...');

// Simulate CLI execution (assuming global install or PATH setup)
const { execSync } = require('child_process');
try {
  execSync('npm i -g merge-yaml-cli', { stdio: 'inherit' });
  const cliCommand = 'merge-yaml -i config/base.yml config/overrides/*.yml -o merged.yml';
  console.log(`Executing: ${cliCommand}`);
  execSync(cliCommand, { stdio: 'inherit' });
  console.log('\nMerged YAML content:');
  console.log(fs.readFileSync('merged.yml', 'utf8'));

  // Clean up dummy files
  fs.unlinkSync('config/base.yml');
  fs.unlinkSync('config/overrides/prod.yml');
  fs.unlinkSync('config/overrides/test.yml');
  fs.unlinkSync('merged.yml');
  fs.rmdirSync('config/overrides');
  fs.rmdirSync('config');
  console.log('\nCleanup complete.');
} catch (error) {
  console.error(`Error during quickstart: ${error.message}`);
  process.exit(1);
}