helm-env-delta 1.3.3 → 1.4.0

package/README.md

@@ -48,6 +48,10 @@ HelmEnvDelta (`hed`) automates environment synchronization for GitOps workflows
 
 📊 **Multiple Reports** - Console, HTML (visual), and JSON (CI/CD) output formats.
 
+🔍 **Discovery Tools** - Preview files (`--list-files`), inspect config (`--show-config`), validate with warnings.
+
+🛡️ **Safety First** - Pre-execution summary, first-run tips, improved error messages with helpful examples.
+
 ⚡ **High Performance** - 45-60% faster than alternatives with intelligent caching and parallel processing.
 
 🔔 **Auto Updates** - Notifies when newer versions are available (skips in CI/CD).
@@ -411,33 +415,42 @@ hed --config <file> [options]  # Short alias
 
 ### Options
 
-| Flag              | Description                                   |
-| ----------------- | --------------------------------------------- |
-| `--config <path>` | **Required** - Configuration file             |
-| `--validate`      | Validate config and exit (no file operations) |
-| `--dry-run`       | Preview changes without writing files         |
-| `--force`         | Override stop rules                           |
-| `--diff`          | Show console diff                             |
-| `--diff-html`     | Generate HTML report (opens in browser)       |
-| `--diff-json`     | Output JSON to stdout (pipe to jq)            |
-| `--skip-format`   | Skip YAML formatting                          |
-| `--verbose`       | Show detailed debug info                      |
-| `--quiet`         | Suppress output except errors                 |
+| Flag              | Description                                      |
+| ----------------- | ------------------------------------------------ |
+| `--config <path>` | **Required** - Configuration file                |
+| `--validate`      | Validate config and exit (shows warnings)        |
+| `--dry-run`       | Preview changes without writing files            |
+| `--force`         | Override stop rules                              |
+| `--diff`          | Show console diff                                |
+| `--diff-html`     | Generate HTML report (opens in browser)          |
+| `--diff-json`     | Output JSON to stdout (pipe to jq)               |
+| `--list-files`    | List source/destination files without processing |
+| `--show-config`   | Display resolved config after inheritance        |
+| `--skip-format`   | Skip YAML formatting                             |
+| `--no-color`      | Disable colored output (CI/accessibility)        |
+| `--verbose`       | Show detailed debug info                         |
+| `--quiet`         | Suppress output except errors                    |
 
 ### Examples
 
 ```bash
-# Validate configuration
+# Validate configuration (shows warnings)
 hed --config config.yaml --validate
 
+# Preview files that will be synced
+hed --config config.yaml --list-files
+
+# Display resolved config (after inheritance)
+hed --config config.yaml --show-config
+
 # Preview with diff
 hed --config config.yaml --dry-run --diff
 
 # Visual HTML report
 hed --config config.yaml --diff-html
 
-# CI/CD integration
-hed --config config.yaml --diff-json | jq '.summary'
+# CI/CD integration (no colors)
+hed --config config.yaml --diff-json --no-color | jq '.summary'
 
 # Execute sync
 hed --config config.yaml
@@ -514,7 +527,7 @@ git push origin main
 
 ✅ **Flexibility** - Per-file patterns. Config inheritance. Regex transforms.
 
-✅ **Reliability** - 763 tests, 84% coverage. Battle-tested.
+✅ **Reliability** - 787 tests, 84% coverage. Battle-tested.
 
 ---
 

package/dist/commandLine.d.ts

@@ -9,5 +9,8 @@ export type SyncCommand = {
     validate: boolean;
     verbose: boolean;
     quiet: boolean;
+    listFiles: boolean;
+    showConfig: boolean;
+    noColor: boolean;
 };
 export declare const parseCommandLine: (argv?: string[]) => SyncCommand;

package/dist/commandLine.js

@@ -20,8 +20,28 @@ const parseCommandLine = (argv) => {
         .option('--diff-json', 'Output diff as JSON to stdout', false)
         .option('--skip-format', 'Skip YAML formatting (outputFormat section)', false)
         .option('--validate', 'Validate configuration file and exit', false)
+        .option('--list-files', 'List files that would be synced without processing diffs', false)
+        .option('--show-config', 'Display resolved configuration after inheritance and exit', false)
+        .option('--no-color', 'Disable colored output')
         .option('--verbose', 'Show detailed debug information', false)
-        .option('--quiet', 'Suppress all output except critical errors', false);
+        .option('--quiet', 'Suppress all output except critical errors', false)
+        .addHelpText('after', `
+Examples:
+  # Preview changes before syncing
+  $ helm-env-delta --config config.yaml --dry-run --diff
+
+  # Sync with HTML diff report
+  $ helm-env-delta --config config.yaml --diff-html
+
+  # Validate stop rules without syncing
+  $ helm-env-delta --config config.yaml --validate
+
+  # CI/CD usage with JSON output
+  $ helm-env-delta --config config.yaml --diff-json | jq '.summary'
+
+Documentation: https://github.com/balazscsaba2006/helm-env-delta
+`);
+    program.showSuggestionAfterError(true);
     program.parse(argv || process.argv);
     const options = program.opts();
     if (options['verbose'] && options['quiet']) {
@@ -37,6 +57,9 @@ const parseCommandLine = (argv) => {
         diffJson: options['diffJson'],
         skipFormat: options['skipFormat'],
         validate: options['validate'],
+        listFiles: options['listFiles'],
+        showConfig: options['showConfig'],
+        noColor: !options['color'],
         verbose: options['verbose'],
         quiet: options['quiet']
     };

package/dist/configMerger.js

@@ -176,8 +176,16 @@ const resolveConfigWithExtends = (configPath, visited = new Set(), depth = 0, lo
             const errorCode = error.code;
             if (errorCode === 'ENOENT') {
                 readError.message += '\n\n  Hint: Config file not found:';
-                readError.message += '\n    - Check the file path is correct';
-                readError.message += '\n    - Use absolute path or path relative to current directory';
+                readError.message += '\n    - Check the file path is correct (use --config path/to/config.yaml)';
+                readError.message +=
+                    '\n    - See examples at: https://github.com/balazscsaba2006/helm-env-delta/tree/main/example';
+                readError.message += '\n    - Start with the basic example: example/0-basic/config.yaml';
+                readError.message += '\n    - Or create a minimal config:';
+                readError.message += '\n';
+                readError.message += '\n      source: ./source-dir';
+                readError.message += '\n      destination: ./dest-dir';
+                readError.message += '\n      skipPath:';
+                readError.message += '\n        "**/*": ["$.metadata.labels"]';
             }
             else if (errorCode === 'EACCES') {
                 readError.message += '\n\n  Hint: Permission denied:';

package/dist/configWarnings.d.ts

@@ -0,0 +1,2 @@
+import type { FinalConfig } from './configFile';
+export declare const validateConfigWarnings: (config: FinalConfig) => string[];

package/dist/configWarnings.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateConfigWarnings = void 0;
+const validateConfigWarnings = (config) => {
+    const warnings = [];
+    const allGlobs = [...config.include, ...config.exclude];
+    for (const glob of allGlobs)
+        if (glob.includes('**/**'))
+            warnings.push(`Inefficient glob pattern '${glob}' detected (use '**/*' instead)`);
+    const includeSet = new Set(config.include);
+    if (includeSet.size < config.include.length)
+        warnings.push('Duplicate patterns found in include array');
+    const excludeSet = new Set(config.exclude);
+    if (excludeSet.size < config.exclude.length)
+        warnings.push('Duplicate patterns found in exclude array');
+    for (const pattern of config.include)
+        if (config.exclude.includes(pattern))
+            warnings.push(`Pattern '${pattern}' appears in both include and exclude (exclude takes precedence)`);
+    if (config.skipPath)
+        for (const [pattern, paths] of Object.entries(config.skipPath))
+            if (paths.length === 0)
+                warnings.push(`skipPath pattern '${pattern}' has empty array (will have no effect)`);
+    if (config.transforms)
+        for (const [pattern, rules] of Object.entries(config.transforms))
+            if ((rules.content?.length ?? 0) === 0 && (rules.filename?.length ?? 0) === 0)
+                warnings.push(`Transform pattern '${pattern}' has empty content and filename arrays (will have no effect)`);
+    return warnings;
+};
+exports.validateConfigWarnings = validateConfigWarnings;

package/dist/index.js

@@ -1,12 +1,51 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = __importDefault(require("node:path"));
+const chalk_1 = __importDefault(require("chalk"));
+const YAML = __importStar(require("yaml"));
 const package_json_1 = __importDefault(require("../package.json"));
 const commandLine_1 = require("./commandLine");
 const configLoader_1 = require("./configLoader");
 const configMerger_1 = require("./configMerger");
+const configWarnings_1 = require("./configWarnings");
 const consoleDiffReporter_1 = require("./consoleDiffReporter");
 const consoleFormatter_1 = require("./consoleFormatter");
 const fileDiff_1 = require("./fileDiff");
@@ -22,12 +61,38 @@ const versionChecker_1 = require("./utils/versionChecker");
 const ZodError_1 = require("./ZodError");
 const main = async () => {
     const command = (0, commandLine_1.parseCommandLine)();
+    if (command.noColor)
+        chalk_1.default.level = 0;
     const verbosityLevel = command.verbose ? 'verbose' : command.quiet ? 'quiet' : 'normal';
     const logger = new logger_1.Logger({ level: verbosityLevel, isDiffJson: command.diffJson });
     logger.log(`Now you run ${package_json_1.default.name} v${package_json_1.default.version}...`);
+    const configDirectory = node_path_1.default.join((0, node_os_1.homedir)(), '.helm-env-delta');
+    const firstRunMarker = node_path_1.default.join(configDirectory, 'first-run');
+    const isFirstRun = !(0, node_fs_1.existsSync)(firstRunMarker);
+    if (isFirstRun && !command.quiet) {
+        console.log(chalk_1.default.cyan('\n👋 First time using helm-env-delta?\n'));
+        console.log(chalk_1.default.dim('  Tips:'));
+        console.log(chalk_1.default.dim('  • Always use --dry-run first to preview changes'));
+        console.log(chalk_1.default.dim('  • Use --diff-html to review diffs in your browser'));
+        console.log(chalk_1.default.dim('  • See examples: https://github.com/balazscsaba2006/helm-env-delta/tree/main/example'));
+        console.log(chalk_1.default.dim('  • Run with --help to see all options\n'));
+        (0, node_fs_1.mkdirSync)(configDirectory, { recursive: true });
+        (0, node_fs_1.writeFileSync)(firstRunMarker, new Date().toISOString());
+    }
     const config = (0, configLoader_1.loadConfigFile)(command.config, command.quiet, logger);
+    if (command.showConfig) {
+        console.log(chalk_1.default.cyan('\n⚙️  Resolved Configuration:\n'));
+        console.log(YAML.stringify(config, { indent: 2 }));
+        return;
+    }
     if (command.validate) {
         logger.log('\n' + (0, consoleFormatter_1.formatProgressMessage)('Configuration is valid', 'success'));
+        const warnings = (0, configWarnings_1.validateConfigWarnings)(config);
+        if (warnings.length > 0) {
+            console.warn(chalk_1.default.yellow('\n⚠️  Validation Warnings (non-fatal):\n'));
+            for (const warning of warnings)
+                console.warn(chalk_1.default.yellow(`  • ${warning}`));
+        }
         return;
     }
     if (logger.shouldShow('debug')) {
@@ -58,6 +123,18 @@ const main = async () => {
         exclude: config.exclude
     }, logger);
     logger.progress(`Loaded ${destinationFiles.size} destination file(s)`, 'success');
+    if (command.listFiles) {
+        const sourceFilesList = [...sourceFiles.keys()].toSorted();
+        const destinationFilesList = [...destinationFiles.keys()].toSorted();
+        console.log(chalk_1.default.cyan('\n📋 Files to be synced:\n'));
+        console.log(chalk_1.default.green(`Source files: ${sourceFilesList.length}`));
+        for (const file of sourceFilesList)
+            console.log(`  ${chalk_1.default.dim(file)}`);
+        console.log(chalk_1.default.yellow(`\nDestination files: ${destinationFilesList.length}`));
+        for (const file of destinationFilesList)
+            console.log(`  ${chalk_1.default.dim(file)}`);
+        return;
+    }
     logger.log('\n' + (0, consoleFormatter_1.formatProgressMessage)('Computing differences...', 'info'));
     const diffResult = (0, fileDiff_1.computeFileDiff)(sourceFiles, destinationFiles, config, logger);
     if (logger.shouldShow('debug'))
@@ -84,6 +161,19 @@ const main = async () => {
             logger.error('\nUse --force to override stop rules or --dry-run to preview changes.', 'critical');
             process.exit(1);
         }
+    if (!command.dryRun && !command.quiet) {
+        console.log(chalk_1.default.cyan('\n📊 Sync Summary:'));
+        console.log(chalk_1.default.dim('─'.repeat(60)));
+        console.log(`  ${chalk_1.default.green('Added:')}     ${diffResult.addedFiles.length} files`);
+        console.log(`  ${chalk_1.default.yellow('Changed:')}   ${diffResult.changedFiles.length} files`);
+        console.log(`  ${chalk_1.default.red('Deleted:')}   ${diffResult.deletedFiles.length} files (${config.prune ? 'prune enabled' : 'prune disabled'})`);
+        console.log(`  ${chalk_1.default.blue('Unchanged:')} ${diffResult.unchangedFiles.length} files`);
+        console.log(chalk_1.default.dim('─'.repeat(60)));
+        if (diffResult.deletedFiles.length > 0 && config.prune)
+            console.warn(chalk_1.default.red('⚠️  Warning: Prune is enabled. Files will be permanently deleted!'));
+        console.log(chalk_1.default.dim('\nPress Ctrl+C to cancel, or use --dry-run to preview changes first.\n'));
+        await new Promise((resolve) => setTimeout(resolve, 2000));
+    }
     const formattedFiles = await (0, fileUpdater_1.updateFiles)(diffResult, sourceFiles, destinationFiles, config, command.dryRun, command.skipFormat, logger);
     if (command.diffHtml && !command.quiet)
         await (0, htmlReporter_1.generateHtmlReport)(diffResult, formattedFiles, config, command.dryRun, logger);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "helm-env-delta",
-  "version": "1.3.3",
+  "version": "1.4.0",
   "description": "HelmEnvDelta – environment-aware YAML delta and sync for GitOps",
   "author": "BCsabaEngine",
   "license": "ISC",