helm-env-delta 1.1.0 → 1.1.2

package/README.md

@@ -1,4 +1,4 @@
-# HelmEnvDelta
+# HelmEnvDelta v1.1.0
 
 [![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)
@@ -13,6 +13,7 @@ HelmEnvDelta (`helm-env-delta` or `hed`) is a CLI tool that safely synchronizes
 ## Table of Contents
 
 - [Why HelmEnvDelta?](#why-helmenvdelta)
+- [Adopting HelmEnvDelta in Existing GitOps Workflows](#adopting-helmenvdelta-in-existing-gitops-workflows)
 - [Key Features](#key-features)
 - [Installation](#installation)
 - [Quick Start](#quick-start)
@@ -59,6 +60,164 @@ Managing multiple Kubernetes/Helm environments in GitOps workflows presents seve
 
 ---
 
+## Adopting HelmEnvDelta in Existing GitOps Workflows
+
+If you're currently managing multiple environments manually in a GitOps workflow, HelmEnvDelta can be seamlessly integrated into your existing processes without disrupting your current setup.
+
+### Before HelmEnvDelta: Manual Environment Sync
+
+Many teams start with manual synchronization between environments:
+
+1. **Manual File Copying**: Copy YAML files from UAT to Production manually
+2. **Find & Replace in IDE**: Use editor search/replace to update environment-specific values
+3. **Visual Diff Review**: Compare files side-by-side to ensure correctness
+4. **Manual Git Commits**: Stage, commit, and push changes individually
+5. **Hope for the Best**: Cross fingers that no environment-specific values were accidentally overwritten
+
+This process works but is:
+
+- **Time-consuming**: 15-30 minutes per sync depending on complexity
+- **Error-prone**: Easy to miss files or make incorrect replacements
+- **Inconsistent**: Different team members may format YAML differently
+- **Unvalidated**: No automated checks for dangerous changes
+- **Difficult to audit**: Hard to track what changed and why
+
+### After HelmEnvDelta: Automated Sync
+
+With HelmEnvDelta, the same workflow becomes:
+
+```bash
+# 1. Preview changes (5 seconds)
+helm-env-delta --config config.yaml --dry-run --diff
+
+# 2. Review in browser (visual confirmation)
+helm-env-delta --config config.yaml --diff-html
+
+# 3. Execute sync (2 seconds)
+helm-env-delta --config config.yaml
+
+# 4. Commit (standard git workflow)
+git add . && git commit -m "Sync UAT to Prod" && git push
+```
+
+**Benefits:**
+
+- **Faster**: Reduces sync time from 15-30 minutes to under 1 minute
+- **Safer**: Stop rules prevent dangerous changes (version downgrades, scaling violations)
+- **Consistent**: Enforces uniform YAML formatting across all files
+- **Auditable**: Clear diff reports show exactly what changed
+- **Repeatable**: Same configuration produces same results every time
+
+### Migration Path: Start Small
+
+You don't need to configure everything at once. Start with a minimal configuration and expand gradually:
+
+**Phase 1: Basic Sync (Day 1)**
+
+```yaml
+source: './uat'
+destination: './prod'
+transforms:
+  '**/*.yaml':
+    content:
+      - find: "-uat\\b"
+        replace: '-prod'
+```
+
+Run `--dry-run --diff` to see what would change. This gives you confidence without modifying any files.
+
+**Phase 2: Add Path Filtering (Week 1)**
+
+```yaml
+skipPath:
+  '**/*.yaml':
+    - 'metadata.namespace'
+    - 'spec.replicas'
+```
+
+Identify fields that should never sync (namespaces, replica counts, resource limits) based on your environment differences.
+
+**Phase 3: Add Safety Rules (Week 2)**
+
+```yaml
+stopRules:
+  '**/*.yaml':
+    - type: 'semverMajorUpgrade'
+      path: 'image.tag'
+    - type: 'numeric'
+      path: 'replicaCount'
+      min: 2
+      max: 10
+```
+
+Add validation rules to catch dangerous changes before they reach production.
+
+**Phase 4: Enforce Formatting (Week 3)**
+
+```yaml
+outputFormat:
+  indent: 2
+  keySeparator: true
+  keyOrders:
+    'apps/*.yaml':
+      - 'apiVersion'
+      - 'kind'
+      - 'metadata'
+      - 'spec'
+```
+
+Standardize YAML formatting to reduce diff noise in git.
+
+### Gradual Adoption Strategy
+
+1. **Start Read-Only**: Use `--dry-run` exclusively for the first week to build confidence
+2. **Single Environment First**: Test with a non-critical environment pair (Dev → QA)
+3. **Expand Configuration**: Add skipPath rules as you discover environment-specific fields
+4. **Add Safety Nets**: Configure stop rules based on incidents you want to prevent
+5. **Full Adoption**: Roll out to all environment pairs once validated
+
+### Validating Your Configuration
+
+Before fully adopting HelmEnvDelta, validate your configuration captures all environment differences:
+
+```bash
+# 1. Run dry-run with diff
+helm-env-delta --config config.yaml --dry-run --diff
+
+# 2. Review changes carefully
+# Look for fields that should be skipped but aren't
+
+# 3. Generate JSON report for detailed analysis
+helm-env-delta --config config.yaml --dry-run --diff-json > report.json
+
+# 4. Check specific fields
+cat report.json | jq '.files.changed[].changes[] | select(.path | contains("namespace"))'
+```
+
+If you see fields changing that shouldn't (like production namespaces or replica counts), add them to `skipPath`.
+
+### Coexistence with Manual Processes
+
+HelmEnvDelta doesn't replace your entire workflow. It complements it:
+
+- **Still use git**: HelmEnvDelta syncs files, you commit them
+- **Still review PRs**: Generate HTML diffs for team review
+- **Still use ArgoCD/Flux**: HelmEnvDelta updates files, your GitOps tool deploys them
+- **Still have manual override**: Use `--force` when you need to bypass safety rules
+
+### Real-World Adoption Example
+
+A typical adoption timeline for a team managing 20+ microservices across 3 environments:
+
+- **Week 1**: Install tool, create basic config, run dry-run on one service
+- **Week 2**: Expand to 5 services, add skipPath rules, first real sync
+- **Week 3**: Add stop rules after catching a version downgrade bug
+- **Week 4**: Standardize YAML formatting across all environments
+- **Month 2**: Full adoption for all services, integrated into CI/CD
+- **Result**: Sync time reduced from 2 hours/week to 10 minutes/week, zero production incidents from sync errors
+
+---
+
 ## Key Features
 
 ```mermaid

package/dist/ZodError.js

@@ -16,8 +16,14 @@ class ZodValidationError extends Error {
         const errors = zodError.issues.map((error) => {
             const path = error.path.length > 0 ? error.path.join('.') : 'root';
             let message = `  - ${path}: ${error.message}`;
-            if (error.code === 'invalid_type' && 'expected' in error && 'received' in error)
+            if (error.code === 'invalid_type' && 'expected' in error && 'received' in error) {
                 message += ` (expected ${error.expected}, got ${error.received})`;
+                if (path.includes('transforms') && error.expected === 'object' && error.received === 'array') {
+                    message += '\n    BREAKING CHANGE: Transform format changed in v2.0.0';
+                    message += '\n    OLD: transforms: { "*.yaml": [{ find: "uat", replace: "prod" }] }';
+                    message += '\n    NEW: transforms: { "*.yaml": { content: [{ find: "uat", replace: "prod" }] } }';
+                }
+            }
             if (error.code === 'unrecognized_keys' && 'keys' in error) {
                 const keys = error.keys;
                 message += `\n    Unknown fields: ${keys.join(', ')}`;

package/dist/configFile.d.ts

@@ -107,8 +107,6 @@ declare const baseConfigSchema: z.ZodObject<{
 }, z.core.$strip>;
 declare const finalConfigSchema: z.ZodObject<{
     source: z.ZodNonOptional<z.ZodOptional<z.ZodString>>;
-    destination: z.ZodNonOptional<z.ZodOptional<z.ZodString>>;
-    skipPath: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>;
     transforms: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
         content: z.ZodOptional<z.ZodArray<z.ZodObject<{
             find: z.ZodString;
@@ -119,6 +117,8 @@ declare const finalConfigSchema: z.ZodObject<{
             replace: z.ZodString;
         }, z.core.$strip>>>;
     }, z.core.$strip>>>;
+    destination: z.ZodNonOptional<z.ZodOptional<z.ZodString>>;
+    skipPath: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>;
     stopRules: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
         type: z.ZodLiteral<"semverMajorUpgrade">;
         path: z.ZodString;

package/dist/configMerger.js

@@ -134,20 +134,31 @@ const mergePerFileRecords = (parent, child) => {
     return merged;
 };
 const resolveConfigWithExtends = (configPath, visited = new Set(), depth = 0) => {
-    if (depth > MAX_EXTENDS_DEPTH)
-        throw new ConfigMergerError('Extends chain exceeds maximum depth of 5', {
+    if (depth > MAX_EXTENDS_DEPTH) {
+        const depthError = new ConfigMergerError('Extends chain exceeds maximum depth of 5', {
             code: 'MAX_DEPTH_EXCEEDED',
             path: configPath,
             depth
         });
+        depthError.message += '\n\n  Hint: Simplify your config inheritance:';
+        depthError.message += '\n    - Maximum depth is 5 levels';
+        depthError.message += `\n    - Current depth: ${depth}`;
+        depthError.message += '\n    - Consider consolidating base configs';
+        throw depthError;
+    }
     const absolutePath = node_path_1.default.resolve(configPath);
     if (visited.has(absolutePath)) {
         const chain = [...visited, absolutePath].map((filePath) => filePath.split('/').pop()).join(' → ');
-        throw new ConfigMergerError('Circular dependency detected in extends chain', {
+        const circularError = new ConfigMergerError('Circular dependency detected in extends chain', {
             code: 'CIRCULAR_DEPENDENCY',
             path: absolutePath,
             chain
         });
+        circularError.message += '\n\n  Hint: Break the circular reference in your extends chain:';
+        circularError.message += '\n    - Review the chain shown above';
+        circularError.message += '\n    - Remove one of the extends references';
+        circularError.message += '\n    - Consider flattening configs into a single file';
+        throw circularError;
     }
     const visitedWithCurrent = new Set(visited);
     visitedWithCurrent.add(absolutePath);
@@ -156,12 +167,25 @@ const resolveConfigWithExtends = (configPath, visited = new Set(), depth = 0) =>
         configContent = (0, node_fs_1.readFileSync)(absolutePath, 'utf8');
     }
     catch (error) {
-        if (error instanceof Error && 'code' in error)
-            throw new ConfigMergerError(`Failed to read config file`, {
+        if (error instanceof Error && 'code' in error) {
+            const readError = new ConfigMergerError(`Failed to read config file`, {
                 code: error.code,
                 path: absolutePath,
                 cause: error
             });
+            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';
+            }
+            else if (errorCode === 'EACCES') {
+                readError.message += '\n\n  Hint: Permission denied:';
+                readError.message += `\n    - Check file permissions: ls -la ${absolutePath}`;
+                readError.message += `\n    - Fix permissions: chmod 644 ${absolutePath}`;
+            }
+            throw readError;
+        }
         throw new ConfigMergerError('Failed to read config file', {
             path: absolutePath,
             cause: error
@@ -186,14 +210,20 @@ const resolveConfigWithExtends = (configPath, visited = new Set(), depth = 0) =>
         (0, node_fs_1.readFileSync)(parentPath, 'utf8');
     }
     catch (error) {
-        if (error instanceof Error && 'code' in error)
-            throw new ConfigMergerError('Extended config file not found', {
+        if (error instanceof Error && 'code' in error) {
+            const extendsError = new ConfigMergerError('Extended config file not found', {
                 code: 'INVALID_EXTENDS_PATH',
                 path: absolutePath,
                 extends: config.extends,
                 resolved: parentPath,
                 cause: error
             });
+            extendsError.message += '\n\n  Hint: Cannot find extended config file:';
+            extendsError.message += '\n    - Check the extends path in your config';
+            extendsError.message += `\n    - Path is resolved relative to: ${node_path_1.default.dirname(absolutePath)}`;
+            extendsError.message += '\n    - Use paths relative to the config file location';
+            throw extendsError;
+        }
         throw new ConfigMergerError('Extended config file not found', {
             code: 'INVALID_EXTENDS_PATH',
             path: absolutePath,

package/dist/fileDiff.js

@@ -85,21 +85,29 @@ const processYamlFile = (filePath, sourceContent, destinationContent, skipPath,
         sourceParsed = yaml_1.default.parse(sourceContent);
     }
     catch (error) {
-        throw new FileDiffError('Failed to parse source YAML file', {
+        const parseError = new FileDiffError('Failed to parse source YAML file', {
             code: 'YAML_PARSE_ERROR',
             path: filePath,
             cause: error instanceof Error ? error : undefined
         });
+        parseError.message += '\n\n  Hint: YAML syntax error in source file:';
+        parseError.message += '\n    - Validate at: https://www.yamllint.com/';
+        parseError.message += '\n    - Common issues: incorrect indentation, missing quotes, invalid characters';
+        throw parseError;
     }
     try {
         destinationParsed = yaml_1.default.parse(destinationContent);
     }
     catch (error) {
-        throw new FileDiffError('Failed to parse destination YAML file', {
+        const parseError = new FileDiffError('Failed to parse destination YAML file', {
             code: 'YAML_PARSE_ERROR',
             path: filePath,
             cause: error instanceof Error ? error : undefined
         });
+        parseError.message += '\n\n  Hint: YAML syntax error in destination file:';
+        parseError.message += '\n    - Validate at: https://www.yamllint.com/';
+        parseError.message += '\n    - Common issues: incorrect indentation, missing quotes, invalid characters';
+        throw parseError;
     }
     const sourceTransformed = (0, transformer_1.applyTransforms)(sourceParsed, filePath, transforms);
     const pathsToSkip = (0, exports.getSkipPathsForFile)(filePath, skipPath);

package/dist/fileLoader.js

@@ -31,19 +31,40 @@ const validateAndResolveBaseDirectory = async (baseDirectory) => {
     const absolutePath = node_path_1.default.isAbsolute(baseDirectory) ? baseDirectory : node_path_1.default.resolve(process.cwd(), baseDirectory);
     try {
         const stats = await (0, promises_1.stat)(absolutePath);
-        if (!stats.isDirectory())
-            throw new FileLoaderError('Base path is not a directory', { code: 'ENOTDIR', path: absolutePath });
+        if (!stats.isDirectory()) {
+            const notDirectoryError = new FileLoaderError('Base path is not a directory', {
+                code: 'ENOTDIR',
+                path: absolutePath
+            });
+            notDirectoryError.message += '\n\n  Hint: The source path must be a directory, not a file:';
+            notDirectoryError.message += `\n    - Current path: ${absolutePath}`;
+            notDirectoryError.message += '\n    - Check your config source/destination paths';
+            notDirectoryError.message += '\n    - Use the parent directory instead';
+            throw notDirectoryError;
+        }
         return absolutePath;
     }
     catch (error) {
         if ((0, exports.isFileLoaderError)(error))
             throw error;
         const nodeError = error;
-        throw new FileLoaderError('Failed to access base directory', {
+        const accessError = new FileLoaderError('Failed to access base directory', {
             code: nodeError.code,
             path: absolutePath,
             cause: nodeError
         });
+        if (nodeError.code === 'ENOENT') {
+            accessError.message += '\n\n  Hint: Directory not found:';
+            accessError.message += '\n    - Check your config source/destination paths';
+            accessError.message += `\n    - Verify directory exists: ls -la ${node_path_1.default.dirname(absolutePath)}`;
+            accessError.message += '\n    - Use absolute paths to avoid ambiguity';
+        }
+        else if (nodeError.code === 'EACCES') {
+            accessError.message += '\n\n  Hint: Permission denied:';
+            accessError.message += `\n    - Check directory permissions: ls -la ${absolutePath}`;
+            accessError.message += `\n    - Fix permissions: chmod 755 ${absolutePath}`;
+        }
+        throw accessError;
     }
 };
 const findMatchingFiles = async (baseDirectory, includePatterns, excludePatterns, transforms) => {
@@ -92,8 +113,16 @@ const readFilesIntoMap = async (baseDirectory, absoluteFilePaths) => {
     const readPromises = absoluteFilePaths.map(async (absolutePath) => {
         try {
             const content = await (0, promises_1.readFile)(absolutePath, 'utf8');
-            if (content.includes('\0'))
-                throw new FileLoaderError('Binary file detected', { code: 'ENOTSUP', path: absolutePath });
+            if (content.includes('\0')) {
+                const binaryError = new FileLoaderError('Binary file detected', {
+                    code: 'ENOTSUP',
+                    path: absolutePath
+                });
+                binaryError.message += '\n\n  Hint: Binary files cannot be processed. Add to exclude:';
+                binaryError.message += "\n    exclude: ['**/*.{png,jpg,pdf,zip,tar,gz,bin}']";
+                binaryError.message += '\n    Or exclude this specific file pattern';
+                throw binaryError;
+            }
             const relativePath = node_path_1.default.relative(baseDirectory, absolutePath);
             return { relativePath, content };
         }

package/dist/fileUpdater.js

@@ -84,11 +84,16 @@ const mergeYamlContent = (destinationContent, processedSourceContent, filePath)
         destinationParsed = yaml_1.default.parse(destinationContent);
     }
     catch (error) {
-        throw new FileUpdaterError('Failed to parse destination YAML for merge', {
+        const parseError = new FileUpdaterError('Failed to parse destination YAML for merge', {
             code: 'YAML_PARSE_ERROR',
             path: filePath,
             cause: error instanceof Error ? error : undefined
         });
+        parseError.message += '\n\n  Hint: YAML syntax error in destination file:';
+        parseError.message += '\n    - Validate at: https://www.yamllint.com/';
+        parseError.message += '\n    - Common issues: incorrect indentation, missing quotes';
+        parseError.message += '\n    - Try --skip-format flag if formatting is the issue';
+        throw parseError;
     }
     let merged;
     try {

package/dist/htmlReporter.js

@@ -552,11 +552,16 @@ const writeHtmlFile = async (htmlContent, outputPath) => {
         await (0, promises_1.writeFile)(outputPath, htmlContent, 'utf8');
     }
     catch (error) {
-        throw new HtmlReporterError('Failed to write HTML report file', {
+        const writeError = new HtmlReporterError('Failed to write HTML report file', {
             code: 'WRITE_FAILED',
             path: outputPath,
             cause: error
         });
+        writeError.message += '\n\n  Hint: Cannot write HTML report:';
+        writeError.message += '\n    - Check temp directory permissions';
+        writeError.message += '\n    - Use --diff for console output instead';
+        writeError.message += '\n    - Or --diff-json to pipe to jq';
+        throw writeError;
     }
 };
 const openInBrowser = async (filePath) => {
@@ -567,11 +572,17 @@ const openInBrowser = async (filePath) => {
         await open(absolutePath);
     }
     catch (error) {
-        throw new HtmlReporterError('Failed to open report in browser', {
+        const openError = new HtmlReporterError('Failed to open report in browser', {
             code: 'BROWSER_OPEN_FAILED',
             path: filePath,
             cause: error
         });
+        const absolutePath = node_path_1.default.resolve(filePath);
+        openError.message += '\n\n  Hint: Open the report manually:';
+        openError.message += `\n    - File location: ${absolutePath}`;
+        openError.message += `\n    - macOS: open ${absolutePath}`;
+        openError.message += `\n    - Linux: xdg-open ${absolutePath}`;
+        throw openError;
     }
 };
 const generateHtmlReport = async (diffResult, formattedFiles, config, dryRun) => {

package/dist/stopRulesValidator.js

@@ -12,6 +12,11 @@ const StopRulesValidatorErrorClass = (0, errors_1.createErrorClass)('Stop Rules
         fullMessage += `\n  Violations (${options['violations'].length}):`;
         for (const v of options['violations'])
             fullMessage += `\n    - ${v.file}:${v.path} (${v.rule.type})`;
+        fullMessage += '\n\n  Hint: Review stop rule violations carefully:';
+        fullMessage += '\n    - Preview changes: --dry-run --diff';
+        fullMessage += '\n    - Override if safe: --force (use with caution!)';
+        fullMessage += '\n    - Semver violations indicate major version changes';
+        fullMessage += '\n    - Numeric violations may indicate unsafe scaling';
     }
     if (options.cause)
         fullMessage += `\n  Cause: ${options.cause.message}`;

package/dist/utils/collisionDetector.js

@@ -33,9 +33,14 @@ const validateNoCollisions = (collisions) => {
     const collisionDetails = collisions
         .map((collision) => `  ${collision.transformedName}: [${collision.originalPaths.join(', ')}]`)
         .join('\n');
-    throw new CollisionDetectorError(`Multiple files transform to the same path:\n${collisionDetails}`, {
+    const collisionError = new CollisionDetectorError(`Multiple files transform to the same path:\n${collisionDetails}`, {
         code: 'DUPLICATE_TRANSFORMED_NAME',
         details: JSON.stringify(collisions)
     });
+    collisionError.message += '\n\n  Hint: Make your filename transforms more specific:';
+    collisionError.message += "\n    - Use more specific patterns: { find: 'app-uat\\.', replace: 'app-prod.' }";
+    collisionError.message += "\n    - Or match on path: { find: 'services/uat/', replace: 'services/prod/' }";
+    collisionError.message += '\n    - Check the collision details above for conflicting files';
+    throw collisionError;
 };
 exports.validateNoCollisions = validateNoCollisions;

package/dist/utils/filenameTransformer.js

@@ -25,32 +25,56 @@ const applySequentialTransforms = (value, rules) => {
             result = result.replace(regex, rule.replace);
         }
         catch (error) {
-            throw new FilenameTransformerError('Failed to apply regex transformation', {
+            const regexError = new FilenameTransformerError('Failed to apply regex transformation', {
                 code: 'REGEX_ERROR',
                 cause: error instanceof Error ? error : undefined
             });
+            regexError.message += `\n\n  Hint: The regex pattern failed to compile. Check for:`;
+            regexError.message += `\n    - Balanced parentheses: (group)`;
+            regexError.message += `\n    - Escaped special chars: \\. \\[ \\]`;
+            regexError.message += `\n    - Valid capture groups: $1, $2, etc.`;
+            regexError.message += `\n    Pattern: ${rule.find}`;
+            throw regexError;
         }
     return result;
 };
 const validateTransformedPath = (transformedPath, originalPath) => {
-    if (!transformedPath || transformedPath.trim() === '')
-        throw new FilenameTransformerError('Transformed path is empty', {
+    if (!transformedPath || transformedPath.trim() === '') {
+        const emptyError = new FilenameTransformerError('Transformed path is empty', {
             code: 'EMPTY_FILENAME',
             path: originalPath
         });
-    if (transformedPath.startsWith('/') || transformedPath.includes('..'))
-        throw new FilenameTransformerError('Path transform attempted traversal outside source/destination', {
+        emptyError.message += '\n\n  Hint: The transform produced an empty path. Check your regex pattern:';
+        emptyError.message += "\n    - Ensure 'replace' value is not empty";
+        emptyError.message += '\n    - Verify pattern matches expected part of filename';
+        throw emptyError;
+    }
+    if (transformedPath.startsWith('/') || transformedPath.includes('..')) {
+        const traversalError = new FilenameTransformerError('Path transform attempted traversal outside source/destination', {
             code: 'PATH_TRAVERSAL',
             path: originalPath,
             details: `Transformed path: ${transformedPath}`
         });
+        traversalError.message += '\n\n  Hint: Filename transforms must not navigate outside source/destination:';
+        traversalError.message += "\n    BAD: { find: 'file\\.yaml', replace: '../file.yaml' }  (contains ..)";
+        traversalError.message += "\n    BAD: { find: 'file', replace: '/etc/passwd' }  (absolute path)";
+        traversalError.message += "\n    GOOD: { find: 'envs/uat/', replace: 'envs/prod/' }";
+        traversalError.message += '\n    This is a security feature to prevent accidental overwrites.';
+        throw traversalError;
+    }
     const invalidChars = /[\u0000-\u001F"*:<>?|]/;
-    if (invalidChars.test(transformedPath))
-        throw new FilenameTransformerError('Transformed path contains invalid characters', {
+    if (invalidChars.test(transformedPath)) {
+        const invalidError = new FilenameTransformerError('Transformed path contains invalid characters', {
             code: 'INVALID_FILENAME',
             path: originalPath,
             details: `Transformed path: ${transformedPath}`
         });
+        invalidError.message += '\n\n  Hint: The transformed path contains characters not allowed in filenames:';
+        invalidError.message += '\n    - Remove control characters (\\x00-\\x1F)';
+        invalidError.message += '\n    - Avoid: " * : < > ? |';
+        invalidError.message += '\n    - Check your regex replacement string';
+        throw invalidError;
+    }
 };
 const getFilenameTransformsForFile = (filePath, transforms) => {
     if (!transforms)

package/dist/utils/transformer.js

@@ -50,11 +50,16 @@ const applyTransforms = (data, filePath, transforms) => {
         return transformValueRecursive(data, matchedRules);
     }
     catch (error) {
-        throw new TransformerError('Failed to apply transformations', {
+        const transformError = new TransformerError('Failed to apply transformations', {
             code: 'TRANSFORM_APPLICATION_ERROR',
             path: filePath,
             cause: error instanceof Error ? error : new Error(String(error))
         });
+        transformError.message += '\n\n  Hint: Common regex issues:';
+        transformError.message += '\n    - Unescaped special chars: use \\. for dots, \\[ for brackets';
+        transformError.message += '\n    - Invalid capture groups: ensure balanced parentheses';
+        transformError.message += '\n    - Test your pattern: https://regex101.com/';
+        throw transformError;
     }
 };
 exports.applyTransforms = applyTransforms;

package/dist/yamlFormatter.js

@@ -47,11 +47,16 @@ const formatYaml = (content, filePath, outputFormat) => {
         return result;
     }
     catch (error) {
-        throw new YamlFormatterError('Failed to format YAML', {
+        const formatError = new YamlFormatterError('Failed to format YAML', {
             code: 'YAML_FORMAT_ERROR',
             path: filePath,
             cause: error instanceof Error ? error : undefined
         });
+        formatError.message += '\n\n  Hint: Formatting failed. Options:';
+        formatError.message += '\n    - Skip formatting: --skip-format';
+        formatError.message += '\n    - Check keyOrders patterns match YAML structure';
+        formatError.message += '\n    - Verify arraySort paths exist in files';
+        throw formatError;
     }
 };
 exports.formatYaml = formatYaml;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "helm-env-delta",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "HelmEnvDelta – environment-aware YAML delta and sync for GitOps",
   "author": "BCsabaEngine",
   "license": "ISC",
@@ -71,9 +71,7 @@
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-simple-import-sort": "^12.1.1",
     "eslint-plugin-unicorn": "^62.0.0",
-    "nodemon": "^3.1.11",
     "prettier": "^3.7.4",
-    "ts-node": "^10.9.2",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.16"
@@ -83,7 +81,6 @@
     "commander": "^14.0.2",
     "diff": "^8.0.2",
     "diff2html": "^3.4.52",
-    "handlebars": "^4.7.8",
     "open": "^11.0.0",
     "picomatch": "^4.0.3",
     "tinyglobby": "^0.2.15",