helm-env-delta 1.1.2 → 1.2.0

package/README.md

@@ -1,4 +1,4 @@
-# HelmEnvDelta v1.1.0
+# HelmEnvDelta
 
 [![npm version](https://img.shields.io/npm/v/helm-env-delta.svg)](https://www.npmjs.com/package/helm-env-delta)
 [![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)
@@ -248,6 +248,7 @@ flowchart LR
 - **Multiple Reporting Formats**: Console diff, HTML report (visual side-by-side), JSON output (CI/CD integration)
 - **Prune Mode**: Remove destination files not present in source
 - **Dry-Run Preview**: Review all changes before applying them
+- **Automatic Update Notifications**: Notifies when newer versions are available on npm (skips in CI/CD environments)
 
 ---
 
@@ -256,9 +257,6 @@ flowchart LR
 ```bash
 # Global installation
 npm install -g helm-env-delta
-
-# Verify installation
-helm-env-delta --version
 ```
 
 **Prerequisites:**
@@ -266,6 +264,8 @@ helm-env-delta --version
 - Node.js >= 22
 - npm >= 9
 
+**Note:** The tool automatically checks for updates on every run and displays a notification if a newer version is available. This check is skipped in CI/CD environments and fails silently if the npm registry is unreachable.
+
 ---
 
 ## Quick Start
@@ -666,21 +666,28 @@ hed --config <file> [options]
 
 ### Options
 
-| Option            | Short | Description                                 | Default      |
-| ----------------- | ----- | ------------------------------------------- | ------------ |
-| `--config <path>` | `-c`  | Path to YAML configuration file             | **required** |
-| `--dry-run`       |       | Preview changes without writing files       | `false`      |
-| `--force`         |       | Override stop rules and proceed             | `false`      |
-| `--diff`          |       | Display console diff for changed files      | `false`      |
-| `--diff-html`     |       | Generate HTML report and open in browser    | `false`      |
-| `--diff-json`     |       | Output diff as JSON to stdout               | `false`      |
-| `--skip-format`   |       | Skip YAML formatting (outputFormat section) | `false`      |
-| `--version`       | `-V`  | Show version number                         |              |
-| `--help`          | `-h`  | Display help                                |              |
+| Option            | Short | Description                                                | Default      |
+| ----------------- | ----- | ---------------------------------------------------------- | ------------ |
+| `--config <path>` | `-c`  | Path to YAML configuration file                            | **required** |
+| `--validate`      |       | Validate configuration file and exit                       | `false`      |
+| `--dry-run`       |       | Preview changes without writing files                      | `false`      |
+| `--force`         |       | Override stop rules and proceed                            | `false`      |
+| `--diff`          |       | Display console diff for changed files                     | `false`      |
+| `--diff-html`     |       | Generate HTML report and open in browser                   | `false`      |
+| `--diff-json`     |       | Output diff as JSON to stdout                              | `false`      |
+| `--skip-format`   |       | Skip YAML formatting (outputFormat section)                | `false`      |
+| `--verbose`       |       | Show detailed debug information (config, transforms, etc.) | `false`      |
+| `--quiet`         |       | Suppress all output except critical errors                 | `false`      |
+| `--help`          | `-h`  | Display help                                               |              |
+
+**Note:** `--verbose` and `--quiet` are mutually exclusive. Machine-readable output (`--diff-json`) always outputs regardless of verbosity.
 
 ### Examples
 
 ```bash
+# Validate configuration file
+helm-env-delta --config config.yaml --validate
+
 # Basic sync
 helm-env-delta --config config.yaml
 

package/dist/commandLine.d.ts

@@ -6,5 +6,8 @@ export type SyncCommand = {
     diffHtml: boolean;
     diffJson: boolean;
     skipFormat: boolean;
+    validate: boolean;
+    verbose: boolean;
+    quiet: boolean;
 };
 export declare const parseCommandLine: (argv?: string[]) => SyncCommand;

package/dist/commandLine.js

@@ -18,9 +18,16 @@ const parseCommandLine = (argv) => {
         .option('--diff', 'Display console diff for changed files', false)
         .option('--diff-html', 'Generate and open HTML diff report in browser', false)
         .option('--diff-json', 'Output diff as JSON to stdout', false)
-        .option('--skip-format', 'Skip YAML formatting (outputFormat section)', false);
+        .option('--skip-format', 'Skip YAML formatting (outputFormat section)', false)
+        .option('--validate', 'Validate configuration file and exit', false)
+        .option('--verbose', 'Show detailed debug information', false)
+        .option('--quiet', 'Suppress all output except critical errors', false);
     program.parse(argv || process.argv);
     const options = program.opts();
+    if (options['verbose'] && options['quiet']) {
+        console.error('Error: --verbose and --quiet flags are mutually exclusive');
+        process.exit(1);
+    }
     return {
         config: options['config'],
         dryRun: options['dryRun'],
@@ -28,7 +35,10 @@ const parseCommandLine = (argv) => {
         diff: options['diff'],
         diffHtml: options['diffHtml'],
         diffJson: options['diffJson'],
-        skipFormat: options['skipFormat']
+        skipFormat: options['skipFormat'],
+        validate: options['validate'],
+        verbose: options['verbose'],
+        quiet: options['quiet']
     };
 };
 exports.parseCommandLine = parseCommandLine;

package/dist/configLoader.d.ts

@@ -1,3 +1,3 @@
 import { type FinalConfig } from './configFile';
 export type Config = FinalConfig;
-export declare const loadConfigFile: (configPath: string) => FinalConfig;
+export declare const loadConfigFile: (configPath: string, quiet?: boolean, logger?: import("./logger").Logger) => FinalConfig;

package/dist/configLoader.js

@@ -3,10 +3,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.loadConfigFile = void 0;
 const configFile_1 = require("./configFile");
 const configMerger_1 = require("./configMerger");
-const loadConfigFile = (configPath) => {
-    const mergedConfig = (0, configMerger_1.resolveConfigWithExtends)(configPath);
+const loadConfigFile = (configPath, quiet = false, logger) => {
+    const mergedConfig = (0, configMerger_1.resolveConfigWithExtends)(configPath, new Set(), 0, logger);
     const config = (0, configFile_1.parseFinalConfig)(mergedConfig, configPath);
-    console.log(`\nConfiguration loaded: ${config.source} -> ${config.destination}` + (config.prune ? ' [prune!]' : ''));
+    if (!quiet)
+        console.log(`\nConfiguration loaded: ${config.source} -> ${config.destination}` + (config.prune ? ' [prune!]' : ''));
     return config;
 };
 exports.loadConfigFile = loadConfigFile;

package/dist/configMerger.d.ts

@@ -17,5 +17,5 @@ export declare class ConfigMergerError extends ConfigMergerErrorClass {
 }
 export declare const isConfigMergerError: (error: unknown) => error is ConfigMergerError;
 export declare const mergeConfigs: (parent: BaseConfig, child: BaseConfig) => BaseConfig;
-export declare const resolveConfigWithExtends: (configPath: string, visited?: Set<string>, depth?: number) => BaseConfig;
+export declare const resolveConfigWithExtends: (configPath: string, visited?: Set<string>, depth?: number, logger?: import("./logger").Logger) => BaseConfig;
 export {};

package/dist/configMerger.js

@@ -133,7 +133,7 @@ const mergePerFileRecords = (parent, child) => {
             merged[pattern] = merged[pattern] === undefined ? [...rules] : [...merged[pattern], ...rules];
     return merged;
 };
-const resolveConfigWithExtends = (configPath, visited = new Set(), depth = 0) => {
+const resolveConfigWithExtends = (configPath, visited = new Set(), depth = 0, logger) => {
     if (depth > MAX_EXTENDS_DEPTH) {
         const depthError = new ConfigMergerError('Extends chain exceeds maximum depth of 5', {
             code: 'MAX_DEPTH_EXCEEDED',
@@ -202,6 +202,10 @@ const resolveConfigWithExtends = (configPath, visited = new Set(), depth = 0) =>
         });
     }
     const config = (0, configFile_1.parseBaseConfig)(rawConfig, absolutePath);
+    if (logger?.shouldShow('debug')) {
+        const filename = absolutePath.split('/').pop();
+        logger.debug(`Loading config: ${filename} (depth: ${depth})`);
+    }
     if (config.extends === undefined)
         return config;
     const configDirectory = node_path_1.default.dirname(absolutePath);
@@ -232,7 +236,9 @@ const resolveConfigWithExtends = (configPath, visited = new Set(), depth = 0) =>
             cause: error
         });
     }
-    const parentConfig = (0, exports.resolveConfigWithExtends)(parentPath, visitedWithCurrent, depth + 1);
+    if (logger?.shouldShow('debug'))
+        logger.debug(`  Extends: ${config.extends} → ${parentPath.split('/').pop()}`);
+    const parentConfig = (0, exports.resolveConfigWithExtends)(parentPath, visitedWithCurrent, depth + 1, logger);
     return (0, exports.mergeConfigs)(parentConfig, config);
 };
 exports.resolveConfigWithExtends = resolveConfigWithExtends;

package/dist/consoleFormatter.d.ts

@@ -1,10 +1,9 @@
 import { StopRuleViolation } from './stopRulesValidator';
-type BoxStyle = 'success' | 'warning' | 'error' | 'info';
-type ProgressStyle = 'loading' | 'success' | 'info';
-type ViolationMode = 'error' | 'warning' | 'force';
-type FileOperation = 'add' | 'update' | 'delete' | 'format';
+export type BoxStyle = 'success' | 'warning' | 'error' | 'info';
+export type ProgressStyle = 'loading' | 'success' | 'info';
+export type ViolationMode = 'error' | 'warning' | 'force';
+export type FileOperation = 'add' | 'update' | 'delete' | 'format';
 export declare const formatBox: (title: string, content: string[], style?: BoxStyle, width?: number) => string;
 export declare const formatStopRuleViolation: (violation: StopRuleViolation, mode: ViolationMode) => string;
 export declare const colorizeFileOperation: (operation: FileOperation, filePath: string, isDryRun: boolean, alreadyDeleted?: boolean) => string;
 export declare const formatProgressMessage: (message: string, style: ProgressStyle) => string;
-export {};

package/dist/fileDiff.d.ts

@@ -37,5 +37,5 @@ export declare class FileDiffError extends FileDiffErrorClass {
 }
 export declare const isFileDiffError: (error: unknown) => error is FileDiffError;
 export declare const getSkipPathsForFile: (filePath: string, skipPath?: Record<string, string[]>) => string[];
-export declare const computeFileDiff: (sourceFiles: FileMap, destinationFiles: FileMap, config: Config) => FileDiffResult;
+export declare const computeFileDiff: (sourceFiles: FileMap, destinationFiles: FileMap, config: Config, logger?: import("./logger").Logger) => FileDiffResult;
 export {};

package/dist/fileDiff.js

@@ -162,7 +162,18 @@ const processChangedFiles = (sourceFiles, destinationFiles, skipPath, transforms
     }
     return { changedFiles, unchangedFiles };
 };
-const computeFileDiff = (sourceFiles, destinationFiles, config) => {
+const computeFileDiff = (sourceFiles, destinationFiles, config, logger) => {
+    if (logger?.shouldShow('debug')) {
+        logger.debug('Computing file differences:');
+        logger.debug(`  Source files: ${sourceFiles.size}`);
+        logger.debug(`  Destination files: ${destinationFiles.size}`);
+        const transformCount = Object.keys(config.transforms || {}).length;
+        if (transformCount > 0)
+            logger.debug(`  Content transform patterns: ${transformCount}`);
+        const skipPathCount = Object.keys(config.skipPath || {}).length;
+        if (skipPathCount > 0)
+            logger.debug(`  SkipPath patterns: ${skipPathCount}`);
+    }
     const addedFiles = detectAddedFiles(sourceFiles, destinationFiles);
     const deletedFiles = config.prune ? detectDeletedFiles(sourceFiles, destinationFiles) : [];
     const { changedFiles, unchangedFiles } = processChangedFiles(sourceFiles, destinationFiles, config.skipPath, config.transforms);

package/dist/fileLoader.d.ts

@@ -23,5 +23,5 @@ declare const FileLoaderErrorClass: {
 export declare class FileLoaderError extends FileLoaderErrorClass {
 }
 export declare const isFileLoaderError: (error: unknown) => error is FileLoaderError;
-export declare const loadFiles: (options: FileLoaderOptions) => Promise<FileMap>;
+export declare const loadFiles: (options: FileLoaderOptions, logger?: import("./logger").Logger) => Promise<FileMap>;
 export {};

package/dist/fileLoader.js

@@ -147,13 +147,33 @@ const readFilesIntoMap = async (baseDirectory, absoluteFilePaths) => {
         });
     }
 };
-const loadFiles = async (options) => {
+const loadFiles = async (options, logger) => {
     const absoluteBaseDirectory = await validateAndResolveBaseDirectory(options.baseDirectory);
     const includePatterns = options.include ?? ['**/*'];
     const excludePatterns = options.exclude ?? [];
     const files = await findMatchingFiles(absoluteBaseDirectory, includePatterns, excludePatterns, options.transforms);
+    if (logger?.shouldShow('debug')) {
+        logger.debug('Glob matching:');
+        logger.debug(`  Directory: ${absoluteBaseDirectory}`);
+        logger.debug(`  Include patterns: ${includePatterns.join(', ')}`);
+        logger.debug(`  Exclude patterns: ${excludePatterns.join(', ')}`);
+        logger.debug(`  Matched: ${files.length} file(s)`);
+    }
     const fileMap = await readFilesIntoMap(absoluteBaseDirectory, files);
     const transformedMap = options.transforms ? (0, filenameTransformer_1.transformFilenameMap)(fileMap, options.transforms) : fileMap;
+    if (options.transforms && logger?.shouldShow('debug')) {
+        logger.debug(`Filename transforms applied: ${fileMap.size} → ${transformedMap.size} files`);
+        let exampleCount = 0;
+        for (const [transformed, content] of transformedMap.entries()) {
+            const original = [...fileMap.entries()].find(([_key, c]) => c === content)?.[0];
+            if (original && original !== transformed) {
+                logger.debug(`  ${original} → ${transformed}`);
+                exampleCount++;
+                if (exampleCount >= 3)
+                    break;
+            }
+        }
+    }
     return sortMapByKeys(transformedMap);
 };
 exports.loadFiles = loadFiles;

package/dist/fileUpdater.d.ts

@@ -1,6 +1,7 @@
 import { Config } from './configFile';
 import { FileDiffResult } from './fileDiff';
 import { FileMap } from './fileLoader';
+import { Logger } from './logger';
 export interface FileUpdateError {
     operation: 'add' | 'update' | 'delete';
     path: string;
@@ -23,5 +24,5 @@ declare const FileUpdaterErrorClass: {
 export declare class FileUpdaterError extends FileUpdaterErrorClass {
 }
 export declare const isFileUpdaterError: (error: unknown) => error is FileUpdaterError;
-export declare const updateFiles: (diffResult: FileDiffResult, sourceFiles: FileMap, destinationFiles: FileMap, config: Config, dryRun: boolean, skipFormat?: boolean) => Promise<string[]>;
+export declare const updateFiles: (diffResult: FileDiffResult, sourceFiles: FileMap, destinationFiles: FileMap, config: Config, dryRun: boolean, skipFormat: boolean, logger: Logger) => Promise<string[]>;
 export {};

package/dist/fileUpdater.js

@@ -117,10 +117,10 @@ const mergeYamlContent = (destinationContent, processedSourceContent, filePath)
         });
     }
 };
-const addFile = async (relativePath, content, absoluteDestinationDirectory, config, dryRun, skipFormat = false) => {
+const addFile = async (relativePath, content, absoluteDestinationDirectory, config, dryRun, skipFormat, logger) => {
     const absolutePath = node_path_1.default.join(absoluteDestinationDirectory, relativePath);
     if (dryRun) {
-        console.log((0, consoleFormatter_1.colorizeFileOperation)('add', relativePath, true));
+        logger.fileOp('add', relativePath, true);
         return;
     }
     let contentToWrite = content;
@@ -142,7 +142,7 @@ const addFile = async (relativePath, content, absoluteDestinationDirectory, conf
     try {
         await ensureParentDirectory(absolutePath);
         await (0, promises_1.writeFile)(absolutePath, contentToWrite, 'utf8');
-        console.log((0, consoleFormatter_1.colorizeFileOperation)('add', relativePath, false));
+        logger.fileOp('add', relativePath, false);
     }
     catch (error) {
         throw new FileUpdaterError('Failed to add file', {
@@ -152,10 +152,10 @@ const addFile = async (relativePath, content, absoluteDestinationDirectory, conf
         });
     }
 };
-const updateFile = async (changedFile, absoluteDestinationDirectory, config, dryRun, skipFormat = false) => {
+const updateFile = async (changedFile, absoluteDestinationDirectory, config, dryRun, skipFormat, logger) => {
     const absolutePath = node_path_1.default.join(absoluteDestinationDirectory, changedFile.path);
     if (dryRun) {
-        console.log((0, consoleFormatter_1.colorizeFileOperation)('update', changedFile.path, true));
+        logger.fileOp('update', changedFile.path, true);
         return;
     }
     let contentToWrite = (0, fileType_1.isYamlFile)(changedFile.path)
@@ -168,7 +168,7 @@ const updateFile = async (changedFile, absoluteDestinationDirectory, config, dry
     try {
         await ensureParentDirectory(absolutePath);
         await (0, promises_1.writeFile)(absolutePath, contentToWrite, 'utf8');
-        console.log((0, consoleFormatter_1.colorizeFileOperation)('update', changedFile.path, false));
+        logger.fileOp('update', changedFile.path, false);
     }
     catch (error) {
         throw new FileUpdaterError('Failed to update file', {
@@ -178,19 +178,19 @@ const updateFile = async (changedFile, absoluteDestinationDirectory, config, dry
         });
     }
 };
-const deleteFile = async (relativePath, absoluteDestinationDirectory, dryRun) => {
+const deleteFile = async (relativePath, absoluteDestinationDirectory, dryRun, logger) => {
     const absolutePath = node_path_1.default.join(absoluteDestinationDirectory, relativePath);
     if (dryRun) {
-        console.log((0, consoleFormatter_1.colorizeFileOperation)('delete', relativePath, true));
+        logger.fileOp('delete', relativePath, true);
         return;
     }
     try {
         await (0, promises_1.unlink)(absolutePath);
-        console.log((0, consoleFormatter_1.colorizeFileOperation)('delete', relativePath, false));
+        logger.fileOp('delete', relativePath, false);
     }
     catch (error) {
         if (error.code === 'ENOENT') {
-            console.log((0, consoleFormatter_1.colorizeFileOperation)('delete', relativePath, false, true));
+            logger.fileOp('delete', relativePath, false, true);
             return;
         }
         throw new FileUpdaterError('Failed to delete file', {
@@ -200,21 +200,25 @@ const deleteFile = async (relativePath, absoluteDestinationDirectory, dryRun) =>
         });
     }
 };
-const updateFiles = async (diffResult, sourceFiles, destinationFiles, config, dryRun, skipFormat = false) => {
-    console.log('\n' + (0, consoleFormatter_1.formatProgressMessage)('Updating files...', 'info'));
+const updateFiles = async (diffResult, sourceFiles, destinationFiles, config, dryRun, skipFormat, logger) => {
+    logger.log('\n' + (0, consoleFormatter_1.formatProgressMessage)('Updating files...', 'info'));
     const absoluteDestinationDirectory = await validateDestinationDirectory(config.destination);
     const errors = [];
+    if (logger.shouldShow('debug'))
+        logger.debug(`Processing ${diffResult.addedFiles.length} new files`);
     for (const relativePath of diffResult.addedFiles)
         try {
             const content = sourceFiles.get(relativePath);
-            await addFile(relativePath, content, absoluteDestinationDirectory, config, dryRun, skipFormat);
+            await addFile(relativePath, content, absoluteDestinationDirectory, config, dryRun, skipFormat, logger);
         }
         catch (error) {
             errors.push({ operation: 'add', path: relativePath, error: error });
         }
+    if (logger.shouldShow('debug'))
+        logger.debug(`Updating ${diffResult.changedFiles.length} changed files`);
     for (const changedFile of diffResult.changedFiles)
         try {
-            await updateFile(changedFile, absoluteDestinationDirectory, config, dryRun, skipFormat);
+            await updateFile(changedFile, absoluteDestinationDirectory, config, dryRun, skipFormat, logger);
         }
         catch (error) {
             errors.push({ operation: 'update', path: changedFile.path, error: error });
@@ -229,11 +233,11 @@ const updateFiles = async (diffResult, sourceFiles, destinationFiles, config, dr
                 if (formatted !== content) {
                     const absolutePath = node_path_1.default.join(absoluteDestinationDirectory, relativePath);
                     if (dryRun)
-                        console.log((0, consoleFormatter_1.colorizeFileOperation)('format', relativePath, true));
+                        logger.fileOp('format', relativePath, true);
                     else {
                         await ensureParentDirectory(absolutePath);
                         await (0, promises_1.writeFile)(absolutePath, formatted, 'utf8');
-                        console.log((0, consoleFormatter_1.colorizeFileOperation)('format', relativePath, false));
+                        logger.fileOp('format', relativePath, false);
                     }
                     formattedFiles.push(relativePath);
                 }
@@ -243,29 +247,29 @@ const updateFiles = async (diffResult, sourceFiles, destinationFiles, config, dr
             }
     for (const relativePath of diffResult.deletedFiles)
         try {
-            await deleteFile(relativePath, absoluteDestinationDirectory, dryRun);
+            await deleteFile(relativePath, absoluteDestinationDirectory, dryRun, logger);
         }
         catch (error) {
             errors.push({ operation: 'delete', path: relativePath, error: error });
         }
     if (dryRun) {
-        console.log('\n[DRY RUN] Would perform:');
-        console.log(`  ${diffResult.addedFiles.length} files would be added`);
-        console.log(`  ${diffResult.changedFiles.length} files would be updated`);
-        console.log(`  ${formattedFiles.length} files would be formatted`);
-        console.log(`  ${diffResult.deletedFiles.length} files would be deleted`);
+        logger.log('\n[DRY RUN] Would perform:');
+        logger.log(`  ${diffResult.addedFiles.length} files would be added`);
+        logger.log(`  ${diffResult.changedFiles.length} files would be updated`);
+        logger.log(`  ${formattedFiles.length} files would be formatted`);
+        logger.log(`  ${diffResult.deletedFiles.length} files would be deleted`);
     }
     else {
-        console.log('\n✓ Files updated successfully:');
-        console.log(`  ${diffResult.addedFiles.length} files added`);
-        console.log(`  ${diffResult.changedFiles.length} files updated`);
-        console.log(`  ${formattedFiles.length} files formatted`);
-        console.log(`  ${diffResult.deletedFiles.length} files deleted`);
+        logger.log('\n✓ Files updated successfully:');
+        logger.log(`  ${diffResult.addedFiles.length} files added`);
+        logger.log(`  ${diffResult.changedFiles.length} files updated`);
+        logger.log(`  ${formattedFiles.length} files formatted`);
+        logger.log(`  ${diffResult.deletedFiles.length} files deleted`);
     }
     if (errors.length > 0) {
-        console.error(`\n❌ Encountered ${errors.length} error(s):`);
+        logger.error(`\n❌ Encountered ${errors.length} error(s):`, 'critical');
         for (const { operation, path: errorPath, error } of errors)
-            console.error(`  [${operation}] ${errorPath}: ${error.message}`);
+            logger.error(`  [${operation}] ${errorPath}: ${error.message}`, 'critical');
         throw new FileUpdaterError(`Failed to update ${errors.length} file(s)`, { code: 'UPDATE_FAILED' });
     }
     return formattedFiles;

package/dist/htmlReporter.d.ts

@@ -23,5 +23,5 @@ declare const HtmlReporterErrorClass: {
 export declare class HtmlReporterError extends HtmlReporterErrorClass {
 }
 export declare const isHtmlReporterError: (error: unknown) => error is HtmlReporterError;
-export declare const generateHtmlReport: (diffResult: FileDiffResult, formattedFiles: string[], config: Config, dryRun: boolean) => Promise<void>;
+export declare const generateHtmlReport: (diffResult: FileDiffResult, formattedFiles: string[], config: Config, dryRun: boolean, logger?: import("./logger").Logger) => Promise<void>;
 export {};

package/dist/htmlReporter.js

@@ -585,7 +585,7 @@ const openInBrowser = async (filePath) => {
         throw openError;
     }
 };
-const generateHtmlReport = async (diffResult, formattedFiles, config, dryRun) => {
+const generateHtmlReport = async (diffResult, formattedFiles, config, dryRun, logger) => {
     const reportPath = generateTemporaryFilePath();
     const metadata = {
         timestamp: new Date().toISOString(),
@@ -598,14 +598,14 @@ const generateHtmlReport = async (diffResult, formattedFiles, config, dryRun) =>
     const changedSections = diffResult.changedFiles.map((file) => generateChangedFileSection(file));
     const htmlContent = generateHtmlTemplate(diffResult, formattedFiles, trulyUnchangedFiles, metadata, changedSections);
     await writeHtmlFile(htmlContent, reportPath);
-    console.log(`✓ HTML report generated: ${reportPath}, opening in browser...`);
+    logger?.log(`✓ HTML report generated: ${reportPath}, opening in browser...`);
     try {
         await openInBrowser(reportPath);
     }
     catch {
         const absolutePath = node_path_1.default.resolve(reportPath);
-        console.log('⚠ Could not open browser automatically. Please open manually:');
-        console.log(`  file://${absolutePath}`);
+        logger?.log('⚠ Could not open browser automatically. Please open manually:');
+        logger?.log(`  file://${absolutePath}`);
     }
 };
 exports.generateHtmlReport = generateHtmlReport;

package/dist/index.js

@@ -14,58 +14,79 @@ const fileLoader_1 = require("./fileLoader");
 const fileUpdater_1 = require("./fileUpdater");
 const htmlReporter_1 = require("./htmlReporter");
 const jsonReporter_1 = require("./jsonReporter");
+const logger_1 = require("./logger");
 const stopRulesValidator_1 = require("./stopRulesValidator");
 const collisionDetector_1 = require("./utils/collisionDetector");
 const filenameTransformer_1 = require("./utils/filenameTransformer");
+const versionChecker_1 = require("./utils/versionChecker");
 const ZodError_1 = require("./ZodError");
 const main = async () => {
-    console.log(`Now you run ${package_json_1.default.name} v${package_json_1.default.version}...`);
     const command = (0, commandLine_1.parseCommandLine)();
-    const config = (0, configLoader_1.loadConfigFile)(command.config);
-    console.log('\n' + (0, consoleFormatter_1.formatProgressMessage)('Loading files...', 'loading'));
+    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 config = (0, configLoader_1.loadConfigFile)(command.config, command.quiet, logger);
+    if (command.validate) {
+        logger.log('\n' + (0, consoleFormatter_1.formatProgressMessage)('Configuration is valid', 'success'));
+        return;
+    }
+    if (logger.shouldShow('debug')) {
+        logger.debug('\nConfig details:');
+        logger.debug(`  Source: ${config.source}`);
+        logger.debug(`  Destination: ${config.destination}`);
+        logger.debug(`  Include patterns: ${config.include.join(', ')}`);
+        logger.debug(`  Exclude patterns: ${config.exclude.join(', ')}`);
+        logger.debug(`  Transforms: ${Object.keys(config.transforms || {}).length} pattern(s)`);
+        logger.debug(`  Prune enabled: ${config.prune}`);
+    }
+    logger.log('\n' + (0, consoleFormatter_1.formatProgressMessage)('Loading files...', 'loading'));
     const sourceFiles = await (0, fileLoader_1.loadFiles)({
         baseDirectory: config.source,
         include: config.include,
         exclude: config.exclude,
         transforms: config.transforms
-    });
-    console.log((0, consoleFormatter_1.formatProgressMessage)(`Loaded ${sourceFiles.size} source file(s)`, 'success'));
+    }, logger);
+    logger.progress(`Loaded ${sourceFiles.size} source file(s)`, 'success');
     const collisions = (0, collisionDetector_1.detectCollisions)(sourceFiles, config.transforms);
     if (collisions.length > 0)
         (0, collisionDetector_1.validateNoCollisions)(collisions);
+    if (logger.shouldShow('debug'))
+        logger.debug('Filename collision check: passed');
     const destinationFiles = await (0, fileLoader_1.loadFiles)({
         baseDirectory: config.destination,
         include: config.include,
         exclude: config.exclude
-    });
-    console.log((0, consoleFormatter_1.formatProgressMessage)(`Loaded ${destinationFiles.size} destination file(s)`, 'success'));
-    console.log('\n' + (0, consoleFormatter_1.formatProgressMessage)('Computing differences...', 'info'));
-    const diffResult = (0, fileDiff_1.computeFileDiff)(sourceFiles, destinationFiles, config);
-    if (command.diff)
+    }, logger);
+    logger.progress(`Loaded ${destinationFiles.size} destination file(s)`, 'success');
+    logger.log('\n' + (0, consoleFormatter_1.formatProgressMessage)('Computing differences...', 'info'));
+    const diffResult = (0, fileDiff_1.computeFileDiff)(sourceFiles, destinationFiles, config, logger);
+    if (logger.shouldShow('debug'))
+        logger.debug('Diff pipeline: parse → transforms → skipPath → normalize → compare');
+    if (command.diff && !command.quiet)
         (0, consoleDiffReporter_1.showConsoleDiff)(diffResult, config);
     else {
-        console.log(`  New files: ${diffResult.addedFiles.length}`);
-        console.log(`  Deleted files: ${diffResult.deletedFiles.length}`);
-        console.log(`  Changed files: ${diffResult.changedFiles.length}`);
-        console.log(`  Unchanged files: ${diffResult.unchangedFiles.length}`);
+        logger.log(`  New files: ${diffResult.addedFiles.length}`);
+        logger.log(`  Deleted files: ${diffResult.deletedFiles.length}`);
+        logger.log(`  Changed files: ${diffResult.changedFiles.length}`);
+        logger.log(`  Unchanged files: ${diffResult.unchangedFiles.length}`);
     }
-    const validationResult = (0, stopRulesValidator_1.validateStopRules)(diffResult, config.stopRules);
+    const validationResult = (0, stopRulesValidator_1.validateStopRules)(diffResult, config.stopRules, logger);
     if (validationResult.violations.length > 0)
         if (command.force)
             for (const violation of validationResult.violations)
-                console.warn('\n' + (0, consoleFormatter_1.formatStopRuleViolation)(violation, 'force'));
+                logger.stopRule(violation, 'force');
         else if (command.dryRun)
             for (const violation of validationResult.violations)
-                console.warn('\n' + (0, consoleFormatter_1.formatStopRuleViolation)(violation, 'warning'));
+                logger.stopRule(violation, 'warning');
         else {
             for (const violation of validationResult.violations)
-                console.error('\n' + (0, consoleFormatter_1.formatStopRuleViolation)(violation, 'error'));
-            console.error('\nUse --force to override stop rules or --dry-run to preview changes.');
+                logger.stopRule(violation, 'error');
+            logger.error('\nUse --force to override stop rules or --dry-run to preview changes.', 'critical');
             process.exit(1);
         }
-    const formattedFiles = await (0, fileUpdater_1.updateFiles)(diffResult, sourceFiles, destinationFiles, config, command.dryRun, command.skipFormat);
-    if (command.diffHtml)
-        await (0, htmlReporter_1.generateHtmlReport)(diffResult, formattedFiles, config, command.dryRun);
+    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);
     if (command.diffJson)
         (0, jsonReporter_1.generateJsonReport)(diffResult, formattedFiles, validationResult, config, command.dryRun, package_json_1.default.version);
 };
@@ -98,4 +119,9 @@ const main = async () => {
             console.error('Unexpected error:', error);
         process.exit(1);
     }
+    finally {
+        const command = (0, commandLine_1.parseCommandLine)();
+        if (!command.quiet)
+            void (0, versionChecker_1.checkForUpdates)(package_json_1.default.version);
+    }
 })();

package/dist/logger.d.ts

@@ -0,0 +1,20 @@
+import { FileOperation, ProgressStyle, ViolationMode } from './consoleFormatter';
+import { StopRuleViolation } from './stopRulesValidator';
+export type VerbosityLevel = 'quiet' | 'normal' | 'verbose';
+export type OutputCategory = 'critical' | 'normal' | 'debug' | 'special';
+export type LoggerOptions = {
+    level: VerbosityLevel;
+    isDiffJson: boolean;
+};
+export declare class Logger {
+    private level;
+    constructor(options: LoggerOptions);
+    shouldShow(category: OutputCategory): boolean;
+    log(message: string, category?: OutputCategory): void;
+    warn(message: string, category?: OutputCategory): void;
+    error(message: string, category?: OutputCategory): void;
+    debug(message: string): void;
+    progress(message: string, style: ProgressStyle): void;
+    fileOp(operation: FileOperation, path: string, isDryRun: boolean, alreadyDeleted?: boolean): void;
+    stopRule(violation: StopRuleViolation, mode: ViolationMode): void;
+}

package/dist/logger.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Logger = void 0;
+const consoleFormatter_1 = require("./consoleFormatter");
+class Logger {
+    level;
+    constructor(options) {
+        this.level = options.level;
+    }
+    shouldShow(category) {
+        if (category === 'special')
+            return true;
+        if (category === 'critical')
+            return true;
+        if (this.level === 'quiet')
+            return false;
+        if (this.level === 'verbose')
+            return true;
+        return category === 'normal';
+    }
+    log(message, category = 'normal') {
+        if (this.shouldShow(category))
+            console.log(message);
+    }
+    warn(message, category = 'normal') {
+        if (this.shouldShow(category))
+            console.warn(message);
+    }
+    error(message, category = 'critical') {
+        if (this.shouldShow(category))
+            console.error(message);
+    }
+    debug(message) {
+        if (this.shouldShow('debug'))
+            console.log(message);
+    }
+    progress(message, style) {
+        if (this.shouldShow('normal'))
+            console.log((0, consoleFormatter_1.formatProgressMessage)(message, style));
+    }
+    fileOp(operation, path, isDryRun, alreadyDeleted = false) {
+        if (this.shouldShow('normal'))
+            console.log((0, consoleFormatter_1.colorizeFileOperation)(operation, path, isDryRun, alreadyDeleted));
+    }
+    stopRule(violation, mode) {
+        const message = '\n' + (0, consoleFormatter_1.formatStopRuleViolation)(violation, mode);
+        if (mode === 'error')
+            this.error(message, 'critical');
+        else
+            this.warn(message, 'critical');
+    }
+}
+exports.Logger = Logger;

package/dist/stopRulesValidator.d.ts

@@ -29,5 +29,5 @@ export interface ValidationResult {
     violations: StopRuleViolation[];
     isValid: boolean;
 }
-export declare const validateStopRules: (diffResult: FileDiffResult, stopRulesConfig?: Record<string, StopRule[]>) => ValidationResult;
+export declare const validateStopRules: (diffResult: FileDiffResult, stopRulesConfig?: Record<string, StopRule[]>, logger?: import("./logger").Logger) => ValidationResult;
 export {};

package/dist/stopRulesValidator.js

@@ -26,14 +26,22 @@ class StopRulesValidatorError extends StopRulesValidatorErrorClass {
 }
 exports.StopRulesValidatorError = StopRulesValidatorError;
 exports.isStopRulesValidatorError = (0, errors_1.createErrorTypeGuard)(StopRulesValidatorError);
-const validateStopRules = (diffResult, stopRulesConfig) => {
+const validateStopRules = (diffResult, stopRulesConfig, logger) => {
     if (!stopRulesConfig)
         return { violations: [], isValid: true };
+    if (logger?.shouldShow('debug')) {
+        const totalRules = Object.values(stopRulesConfig).reduce((sum, rules) => sum + rules.length, 0);
+        logger.debug('Stop rule validation:');
+        logger.debug(`  Total rules: ${totalRules}`);
+        logger.debug(`  Files to check: ${diffResult.changedFiles.length}`);
+    }
     const violations = [];
     for (const changedFile of diffResult.changedFiles) {
         const fileViolations = validateFileAgainstRules(changedFile, stopRulesConfig);
         violations.push(...fileViolations);
     }
+    if (logger?.shouldShow('debug'))
+        logger.debug(`Stop rules: ${violations.length} violation(s) found`);
     return {
         violations,
         isValid: violations.length === 0

package/dist/utils/index.d.ts

@@ -5,3 +5,4 @@ export { normalizeForComparison, serializeForDiff } from './serialization';
 export { getValueAtPath, parseJsonPath } from './jsonPath';
 export { isYamlFile } from './fileType';
 export { generateUnifiedDiff } from './diffGenerator';
+export { checkForUpdates, isVersionCheckerError, VersionCheckerError } from './versionChecker';

package/dist/utils/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.generateUnifiedDiff = exports.isYamlFile = exports.parseJsonPath = exports.getValueAtPath = exports.serializeForDiff = exports.normalizeForComparison = exports.deepEqual = exports.createErrorTypeGuard = exports.createErrorClass = void 0;
+exports.VersionCheckerError = exports.isVersionCheckerError = exports.checkForUpdates = exports.generateUnifiedDiff = exports.isYamlFile = exports.parseJsonPath = exports.getValueAtPath = exports.serializeForDiff = exports.normalizeForComparison = exports.deepEqual = exports.createErrorTypeGuard = exports.createErrorClass = void 0;
 var errors_1 = require("./errors");
 Object.defineProperty(exports, "createErrorClass", { enumerable: true, get: function () { return errors_1.createErrorClass; } });
 Object.defineProperty(exports, "createErrorTypeGuard", { enumerable: true, get: function () { return errors_1.createErrorTypeGuard; } });
@@ -16,3 +16,7 @@ var fileType_1 = require("./fileType");
 Object.defineProperty(exports, "isYamlFile", { enumerable: true, get: function () { return fileType_1.isYamlFile; } });
 var diffGenerator_1 = require("./diffGenerator");
 Object.defineProperty(exports, "generateUnifiedDiff", { enumerable: true, get: function () { return diffGenerator_1.generateUnifiedDiff; } });
+var versionChecker_1 = require("./versionChecker");
+Object.defineProperty(exports, "checkForUpdates", { enumerable: true, get: function () { return versionChecker_1.checkForUpdates; } });
+Object.defineProperty(exports, "isVersionCheckerError", { enumerable: true, get: function () { return versionChecker_1.isVersionCheckerError; } });
+Object.defineProperty(exports, "VersionCheckerError", { enumerable: true, get: function () { return versionChecker_1.VersionCheckerError; } });

package/dist/utils/versionChecker.d.ts

@@ -0,0 +1,19 @@
+declare const VersionCheckerErrorClass: {
+    new (message: string, options?: import("./errors").ErrorOptions): {
+        [key: string]: unknown;
+        readonly code?: string;
+        readonly path?: string;
+        readonly cause?: Error;
+        name: string;
+        message: string;
+        stack?: string;
+    };
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+};
+export declare class VersionCheckerError extends VersionCheckerErrorClass {
+}
+export declare const isVersionCheckerError: (error: unknown) => error is VersionCheckerError;
+export declare const checkForUpdates: (currentVersion: string) => Promise<void>;
+export {};

package/dist/utils/versionChecker.js

@@ -0,0 +1,117 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkForUpdates = exports.isVersionCheckerError = exports.VersionCheckerError = void 0;
+const node_https_1 = __importDefault(require("node:https"));
+const chalk_1 = __importDefault(require("chalk"));
+const package_json_1 = __importDefault(require("../../package.json"));
+const errors_1 = require("./errors");
+const VersionCheckerErrorClass = (0, errors_1.createErrorClass)('Version Checker Error', {
+    TIMEOUT: 'Request timed out',
+    NETWORK: 'Network request failed',
+    PARSE: 'Failed to parse response',
+    INVALID: 'Invalid response format'
+});
+class VersionCheckerError extends VersionCheckerErrorClass {
+}
+exports.VersionCheckerError = VersionCheckerError;
+exports.isVersionCheckerError = (0, errors_1.createErrorTypeGuard)(VersionCheckerError);
+const isCiEnvironment = () => {
+    const ciEnvironmentVariables = [
+        'CI',
+        'CONTINUOUS_INTEGRATION',
+        'BUILD_NUMBER',
+        'GITHUB_ACTIONS',
+        'GITLAB_CI',
+        'CIRCLECI',
+        'TRAVIS',
+        'JENKINS_HOME',
+        'TEAMCITY_VERSION',
+        'TF_BUILD'
+    ];
+    return ciEnvironmentVariables.some((environmentVariable) => process.env[environmentVariable]);
+};
+const parseVersion = (version) => {
+    const semverRegex = /^v?(\d+)\.(\d+)\.(\d+)/;
+    const match = semverRegex.exec(version);
+    if (!match)
+        return undefined;
+    return {
+        major: Number.parseInt(match[1], 10),
+        minor: Number.parseInt(match[2], 10),
+        patch: Number.parseInt(match[3], 10)
+    };
+};
+const isNewerVersion = (current, latest) => {
+    const currentParts = parseVersion(current);
+    const latestParts = parseVersion(latest);
+    if (!currentParts || !latestParts)
+        return false;
+    if (latestParts.major > currentParts.major)
+        return true;
+    if (latestParts.major < currentParts.major)
+        return false;
+    if (latestParts.minor > currentParts.minor)
+        return true;
+    if (latestParts.minor < currentParts.minor)
+        return false;
+    return latestParts.patch > currentParts.patch;
+};
+const fetchLatestVersion = (packageName, timeout) => {
+    return new Promise((resolve, reject) => {
+        const url = `https://registry.npmjs.org/${packageName}/latest`;
+        const request = node_https_1.default.request(url, {
+            headers: {
+                Accept: 'application/json',
+                'User-Agent': `helm-env-delta/${package_json_1.default.version}`
+            },
+            signal: AbortSignal.timeout(timeout)
+        }, (response) => {
+            let data = '';
+            response.on('data', (chunk) => {
+                data += chunk;
+            });
+            response.on('end', () => {
+                if (response.statusCode !== 200) {
+                    reject(new VersionCheckerError(`HTTP ${response.statusCode}`, { code: 'NETWORK' }));
+                    return;
+                }
+                try {
+                    const json = JSON.parse(data);
+                    if (!json.version) {
+                        reject(new VersionCheckerError('Missing version field', { code: 'INVALID' }));
+                        return;
+                    }
+                    resolve(json.version);
+                }
+                catch {
+                    reject(new VersionCheckerError('Invalid JSON response', { code: 'PARSE' }));
+                }
+            });
+        });
+        request.on('error', (error) => {
+            const isTimeout = error.name === 'AbortError';
+            const code = isTimeout ? 'TIMEOUT' : 'NETWORK';
+            reject(new VersionCheckerError(error.message, { code, cause: error }));
+        });
+        request.end();
+    });
+};
+const displayUpdateNotification = (currentVersion, latestVersion) => {
+    console.log('\n' + chalk_1.default.yellow(`⚠ Update available! v${currentVersion} → v${latestVersion}`));
+    console.log(chalk_1.default.yellow('Run: npm install -g helm-env-delta@latest'));
+};
+const checkForUpdates = async (currentVersion) => {
+    if (isCiEnvironment())
+        return;
+    try {
+        const latestVersion = await fetchLatestVersion('helm-env-delta', 3000);
+        if (isNewerVersion(currentVersion, latestVersion))
+            displayUpdateNotification(currentVersion, latestVersion);
+    }
+    catch {
+    }
+};
+exports.checkForUpdates = checkForUpdates;

package/package.json

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