timonel 2.14.0-beta.1 → 3.0.0

package/README.md

@@ -17,18 +17,102 @@ directory.
 
 ## ✨ Key Features
 
+### Core Capabilities
+
 - **🔒 Type-safe API** with strict TypeScript and cdk8s constructs
-- **🎯 Type-Safe Helm Helpers** with 9 composable template helpers (`helmIf`, `helmRange`,
-  `helmWith`, `helmInclude`, etc.)
 - **🔧 Flexible resource creation** with built-in methods and `addManifest()` for custom resources
 - **🌍 Multi-environment support** with automatic values files generation
 - **☂️ Umbrella Charts** for managing multiple subcharts as a single unit
-- **🛠️ Enhanced Helm Helpers** with environment, GitOps, observability, and validation helpers
-- **☁️ Cloud integrations**:
-  - **AWS**: EBS/EFS StorageClass, ALB Ingress, IRSA ServiceAccount, ECR, and Karpenter
-- **🛡️ Security-first approach** with NetworkPolicies and best practices
-- **⚡ Minimal CLI** (`tl`) for scaffolding and chart generation
-- **📦 Flexible subchart templates** supporting cdk8s and cdk8s-plus-33
+- **⚡ Minimal CLI** (`tl`) for scaffolding, synthesis, validation, and deployment
+- **📦 Flexible subchart templates** supporting both cdk8s and cdk8s-plus-33
+
+### Type-Safe Helm Helpers (v3.0+)
+
+#### ValuesRef System (NEW in v3.0 - RECOMMENDED)
+
+Type-safe proxy-based values references with full IDE support:
+
+- Import: `import { valuesRef } from 'timonel'`
+- **Comparison operators**: `eq`, `ne`, `gt`, `ge`, `lt`, `le`
+- **Logical operators**: `not`, `and`, `or`
+- **String functions**: `quote`, `upper`, `lower`, `trim`, `replace`, `contains`
+- **Default values**: `default()`
+- **Type checking**: `kindIs`, `hasKey`
+- **YAML functions**: `toYaml`, `toJson`, `nindent`, `indent`
+- **Field-level conditionals**: `v.if()`, `v.ifElse()` - Complex conditional logic
+- **Range loops**: `v.range()` - Type-safe iteration
+- **Context switching**: `v.with()` - Scoped value access
+
+#### Composable Helpers
+
+Template definition and inclusion helpers:
+
+- `helmInclude`, `helmDefine`, `helmVar`, `helmBlock`, `helmComment`, `helmFragment`
+- `template`, `include`, `quote`, `indent`
+
+#### Value Reference Helpers
+
+Useful string-based utilities (no ValuesRef equivalent):
+
+- `requiredValuesRef` - Required value with validation
+- `numberRef`, `boolRef`, `floatRef` - Type-cast references (int, bool, float64)
+- `base64Ref` - Base64 encoding
+
+#### Legacy Helpers (NOT RECOMMENDED)
+
+**⚠️ Use ValuesRef system instead:**
+
+- `valuesRef(path)` → use `v.path` (ValuesRef system)
+- `stringRef()` → use `v.quote()` (ValuesRef system)
+- `defaultRef()` → use `v.default()` (ValuesRef system)
+- `jsonRef()` → use `v.toJson()` (ValuesRef system)
+- `conditionalRef()` → use `v.if()` (ValuesRef system)
+- `helmIf`, `helmIfSimple` → use `v.if()` (ValuesRef system)
+- `helmRange` → use `v.range()` (ValuesRef system)
+- `helmWith` → use `v.with()` (ValuesRef system)
+- `helmIfElseIf` → use `v.if()` with nested conditions
+
+### Enhanced Helm Helpers
+
+- **Environment Helpers**: `envRef`, `envDefault`, `envRequired`, `envFromSecret`, `envFromConfigMap`
+- **GitOps Helpers**: `gitBranch`, `gitCommit`, `gitTag`, `gitopsAnnotations`
+- **Observability Helpers**: `prometheusAnnotations`, `datadogAnnotations`, `tracingAnnotations`
+- **Validation Helpers**: `validateRequired`, `validatePattern`, `validateRange`, `validateEnum`
+- **Standard Helpers**: 40+ built-in Helm helpers (chart.name, chart.fullname, chart.labels, etc.)
+
+### Cloud Integrations
+
+- **AWS Resources**:
+  - EBS/EFS StorageClass with encryption and performance options
+  - ALB Ingress with SSL/TLS and health checks
+  - IRSA ServiceAccount for pod-level IAM roles
+  - ECR integration
+  - Karpenter NodePool, NodeClaim, and EC2NodeClass
+- **Karpenter Features**:
+  - Disruption budgets and consolidation policies
+  - Instance type selection and requirements
+  - Spot instance support
+  - Custom AMI and user data
+
+### Security & Validation
+
+- **🛡️ Security-first approach**:
+  - Input validation (CWE-20, CWE-22/23)
+  - Path traversal prevention
+  - Command injection prevention (CWE-78/77/88)
+  - Log injection protection (CWE-117)
+  - Code injection prevention (CWE-94)
+- **NetworkPolicy support** for pod-level network isolation
+- **Helm chart validation** with `validateHelmYaml`
+- **SecurityUtils** for path validation and sanitization
+
+### Developer Experience
+
+- **Structured logging** with Pino (JSON format, performance tracking)
+- **Environment variables loader** for external configuration
+- **YAML serialization** with Helm template preservation
+- **TypeScript strict mode** with all compiler checks enabled
+- **Comprehensive error handling** with detailed messages
 
 ## 🚀 Quick Start
 
@@ -153,18 +237,114 @@ const umbrellaConfig = {
 export const umbrella = new UmbrellaChartTemplate(umbrellaConfig);
 ```
 
-### Type-Safe Helm Helpers
+### Using Type-Safe Helm Helpers
+
+#### ValuesRef System (Recommended)
+
+The new ValuesRef system provides a type-safe, proxy-based approach to Helm values with full IDE support.
+
+**⚠️ Important:** This is completely different from the legacy `valuesRef(path: string)` helper.
+The new system uses generics and returns a proxy object with methods.
+
+```typescript
+import { valuesRef } from 'timonel';
+
+interface MyValues {
+  replicaCount: number;
+  image: { repository: string; tag: string };
+  autoscaling: { enabled: boolean; minReplicas: number };
+}
+
+const v = valuesRef<MyValues>();
+
+// Type-safe value references with IDE autocomplete
+const replicas = v.replicaCount; // {{ .Values.replicaCount }}
+const imageTag = v.image.tag; // {{ .Values.image.tag }}
+
+// Comparison operators
+const isProd = v.environment.eq('production'); // eq .Values.environment "production"
+const hasReplicas = v.replicaCount.gt(1); // gt .Values.replicaCount 1
+
+// Logical operators
+const notEnabled = v.autoscaling.enabled.not(); // not .Values.autoscaling.enabled
+
+// String functions
+const upperEnv = v.environment.upper(); // .Values.environment | upper
+const quotedTag = v.image.tag.quote(); // .Values.image.tag | quote
+
+// Default values
+const port = v.port.default(8080); // {{ .Values.port | default 8080 }}
+
+// Field-level conditionals
+const deployment = {
+  spec: {
+    replicas: v.if(notEnabled, v.replicaCount), // Conditionally include field
+  },
+};
+
+// Range loops
+const envVars = v.env.range((item, index) => ({
+  name: item.name,
+  value: item.value,
+}));
+
+// Context switching
+const dbConfig = v.database.with((db) => ({
+  host: db.host,
+  port: db.port,
+}));
+```
+
+#### Template Composition Helpers
+
+Use these helpers for template definitions and inclusions:
+
+```typescript
+import { helmInclude, helmDefine, helmFragment } from 'timonel';
+
+// Template inclusion with pipe
+const labels = helmInclude('chart.labels', '.', { pipe: 'nindent 4' });
+
+// Define a named template
+const myTemplate = helmDefine('myapp.config', {
+  key: 'value',
+});
+
+// Combine multiple constructs
+const combined = helmFragment(helmInclude('chart.labels', '.'), { customKey: 'customValue' });
+```
+
+#### Legacy Flow Control (NOT RECOMMENDED)
+
+**⚠️ These are legacy and NOT RECOMMENDED. Use ValuesRef system (v.if, v.range, v.with)
+instead:**
+
+```typescript
+// ❌ OLD WAY - string-based valuesRef (no type safety)
+const oldRef = valuesRef('.Values.production');
+
+// ✅ NEW WAY - ValuesRef system (type-safe)
+const v = valuesRef<MyValues>();
+const newRef = v.production; // {{ .Values.production }}
+
+// ❌ OLD WAY - helmIf, helmRange, helmWith (string-based)
+const config = helmIf('.Values.production', { replicas: 5 }, { replicas: 1 });
+
+// ✅ NEW WAY - v.if(), v.range(), v.with() (type-safe)
+const config = v.if(v.production, { replicas: 5 });
+```
 
-Timonel provides 9 composable, type-safe helpers for Helm template generation: `helmIf`,
-`helmRange`, `helmWith`, `helmInclude`, `helmDefine`, `helmVar`, `helmBlock`, `helmComment`, and
-`helmFragment`.
+**Why ValuesRef is Better:**
 
-**Benefits:**
+- ✅ **100% Type-Safe** - Catch errors at compile time with TypeScript generics
+- ✅ **No Raw Strings** - Eliminate manual template interpolation and typos
+- ✅ **Full IDE Support** - Autocomplete, type hints, and refactoring support
+- ✅ **Proxy-based** - Chainable methods for complex logic
+- ✅ **Composable** - Nest and combine operations naturally
+- ❌ **Legacy helpers** - String-based, error-prone, no IDE support
 
-- ✅ 100% Type-Safe - catch errors at compile time
-- ✅ No Raw Strings - eliminate manual template interpolation
-- ✅ Composable - nest and combine helpers freely
-- ✅ Full IDE Support - autocomplete and type hints
+**Migration:** Replace `valuesRef(path)` with `v.path`. Replace `helmIf`, `helmRange`, `helmWith`
+with `v.if()`, `v.range()`, `v.with()`.
 
 **Learn more:** See the
 [Type-Safe Helm Helpers Guide](https://github.com/KenkoGeek/timonel/wiki/Helm-Helpers-System) for
@@ -200,10 +380,10 @@ If you get `Error: Cannot find module 'cdk8s'` when running `tl umbrella synth`:
   "version": "1.0.0",
   "type": "module",
   "dependencies": {
-    "cdk8s": "^2.70.16",
-    "cdk8s-plus-33": "^2.3.8",
-    "constructs": "^10.4.2",
-    "timonel": "^2.11.0"
+    "cdk8s": "^2.70.28",
+    "cdk8s-plus-33": "^2.4.6",
+    "constructs": "^10.4.3",
+    "timonel": "^3.0.0-beta.1"
   },
   "devDependencies": {
     "@types/node": "^24.5.2",
@@ -238,7 +418,7 @@ MIT
 [security-url]: SECURITY.md
 [pnpm-badge]: https://img.shields.io/badge/pm-pnpm-ffd95a?logo=pnpm&logoColor=fff&labelColor=24292e
 [pnpm-url]: https://pnpm.io/
-[node-badge]: https://img.shields.io/badge/node-%3E%3D20-339933?logo=node.js&logoColor=fff
+[node-badge]: https://img.shields.io/badge/node-%3E%3D22-339933?logo=node.js&logoColor=fff
 [node-url]: https://nodejs.org/
 [ts-badge]: https://img.shields.io/badge/TypeScript-5.x-3178C6?logo=typescript&logoColor=fff
 [ts-url]: https://www.typescriptlang.org/

package/SECURITY.md

@@ -36,13 +36,14 @@ We provide security updates for the following versions:
 
 <!-- markdownlint-disable MD060 -->
 
-| Version | Supported      | Security Updates | End of Life |
-| ------- | -------------- | ---------------- | ----------- |
-| 2.4.0+  | ✅ Current     | Full support     | TBD         |
-| 2.3.x   | ✅ Supported   | Full support     | TBD         |
-| 2.0-2.2 | ⚠️ Limited     | Critical only    | 2024-12-31  |
-| 1.x.x   | ❌ End of life | None             | 2024-06-30  |
-| < 1.0   | ❌ End of life | None             | 2024-01-01  |
+| Version      | Supported      | Security Updates | End of Life |
+| ------------ | -------------- | ---------------- | ----------- |
+| 3.0.0-beta.1 | ✅ Current     | Full support     | TBD         |
+| 2.14.x       | ✅ Supported   | Full support     | TBD         |
+| 2.8.0-2.13.x | ✅ Supported   | Full support     | 2025-06-30  |
+| 2.0-2.7.x    | ⚠️ Limited     | Critical only    | 2025-03-31  |
+| 1.x.x        | ❌ End of life | None             | 2024-06-30  |
+| < 1.0        | ❌ End of life | None             | 2024-01-01  |
 
 **Update policy:**
 
@@ -83,15 +84,28 @@ We provide security updates for the following versions:
 ### Security Features
 
 - **Input validation**: Comprehensive path traversal prevention and sanitization via SecurityUtils
-- **Log injection protection**: All user inputs sanitized before logging
-- **Code injection prevention**: Strict validation for dynamic module loading
-- **TypeScript strict mode**: Compile-time safety checks
+  - CWE-22/23: Path traversal protection with URL-encoded sequence detection
+  - CWE-20: Proper input validation for CLI flags (--set, --env)
+  - Null byte injection prevention
+  - Reserved key validation in resource providers
+- **Log injection protection**: All user inputs sanitized before logging (CWE-117)
+- **Code injection prevention**: Strict validation for dynamic module loading (CWE-94)
+  - Regex escaping for dynamic pattern construction
+  - Function name validation before template generation
+- **Command injection prevention**: Validated inputs for all shell commands (CWE-78/77/88)
+  - Release name validation (RFC 1123 subdomain)
+  - Namespace validation (Kubernetes naming rules)
+  - --set flag validation with support for nested paths and arrays
+- **TypeScript strict mode**: Compile-time safety checks with all strict options enabled
 - **No eval()**: Static code generation only
 - **File system isolation**: Controlled output directory access with path validation
+  - Absolute path support with explicit allowAbsolute flag
+  - Base directory validation for all file operations
 - **Helm template validation**: Input validation for all template functions
 - **Karpenter security**: Secure node pool and scheduling configurations
 - **Performance optimization**: Efficient algorithms preventing DoS via resource exhaustion
-- **OWASP compliance**: Following secure coding guidelines (CWE-22, CWE-94, CWE-117)
+- **OWASP compliance**: Following secure coding guidelines (CWE-22, CWE-23, CWE-94, CWE-117,
+  CWE-78, CWE-77, CWE-88, CWE-20)
 
 ## Security Considerations for Users
 

package/dist/cli.js

@@ -142,8 +142,9 @@ async function cmdInit(name, silent = false) {
     if (!SecurityUtils.isValidChartName(validName)) {
         usageAndExit('Invalid chart name. Must be lowercase, start with a letter, and contain only letters, numbers, and dashes.');
     }
-    const base = path.join(process.cwd(), validName);
-    const chartFile = path.join(base, 'chart.ts');
+    const cwd = process.cwd();
+    const base = SecurityUtils.validatePath(path.join(cwd, validName), cwd);
+    const chartFile = SecurityUtils.validatePath(path.join(base, 'chart.ts'), cwd);
     fs.mkdirSync(base, { recursive: true });
     const { generateFlexibleSubchartTemplate } = await import('./lib/templates/flexible-subchart.js');
     fs.writeFileSync(chartFile, generateFlexibleSubchartTemplate(validName));
@@ -152,19 +153,31 @@ async function cmdInit(name, silent = false) {
     log(`Run 'tl synth ${validName}' to generate complete Helm chart`, silent);
 }
 async function cmdSynth(chartDirOrOutDir, flags, explicitOutDir) {
-    let chartDir = process.cwd();
+    const cwd = process.cwd();
+    let chartDir = cwd;
     let outDir;
-    if (chartDirOrOutDir && fs.existsSync(path.join(chartDirOrOutDir, 'chart.ts'))) {
-        chartDir = path.resolve(chartDirOrOutDir);
-    }
-    else {
-        outDir = chartDirOrOutDir;
+    if (chartDirOrOutDir) {
+        const resolvedPath = path.resolve(chartDirOrOutDir);
+        const validatedPath = SecurityUtils.validatePath(resolvedPath, cwd, { allowAbsolute: true });
+        const chartTsPath = SecurityUtils.validatePath(path.join(validatedPath, 'chart.ts'), cwd, {
+            allowAbsolute: true,
+        });
+        if (fs.existsSync(chartTsPath)) {
+            chartDir = validatedPath;
+        }
+        else {
+            outDir = chartDirOrOutDir;
+        }
     }
     if (explicitOutDir) {
         outDir = explicitOutDir;
     }
-    const chartFile = path.join(chartDir, 'chart.ts');
-    const defaultOutDir = path.join(chartDir, 'dist');
+    const chartFile = SecurityUtils.validatePath(path.join(chartDir, 'chart.ts'), cwd, {
+        allowAbsolute: true,
+    });
+    const defaultOutDir = SecurityUtils.validatePath(path.join(chartDir, 'dist'), cwd, {
+        allowAbsolute: true,
+    });
     if (!fs.existsSync(chartFile)) {
         console.error('chart.ts not found. Run `tl init` first.');
         process.exit(1);
@@ -177,7 +190,7 @@ async function cmdSynth(chartDirOrOutDir, flags, explicitOutDir) {
     if (modifiedContent === originalContent) {
         modifiedContent = originalContent.replace(/chart\.write\(['"][^'"]*['"]\)/, `chart.write('${safeOutDirLiteral}')`);
     }
-    const tempChartFile = path.join(chartDir, '.timonel-temp-chart.ts');
+    const tempChartFile = SecurityUtils.validatePath(path.join(chartDir, '.timonel-temp-chart.ts'), cwd, { allowAbsolute: true });
     fs.writeFileSync(tempChartFile, modifiedContent);
     const wrapperScript = `
 import { pathToFileURL } from 'url';
@@ -237,11 +250,34 @@ async function cmdValidate(flags) {
         process.exit(result.status ?? 1);
     }
 }
+function validateReleaseName(release) {
+    if (!/^[a-z0-9]([-a-z0-9]*[a-z0-9])?$/.test(release) || release.length > 53) {
+        console.error(`Invalid release name: ${SecurityUtils.sanitizeLogMessage(release)}`);
+        console.error('Release name must be lowercase alphanumeric with hyphens (max 53 chars)');
+        process.exit(1);
+    }
+}
+function validateNamespace(namespace) {
+    if (!/^[a-z0-9]([-a-z0-9]*[a-z0-9])?$/.test(namespace) || namespace.length > 63) {
+        console.error(`Invalid namespace: ${SecurityUtils.sanitizeLogMessage(namespace)}`);
+        console.error('Namespace must be lowercase alphanumeric with hyphens (max 63 chars)');
+        process.exit(1);
+    }
+}
+function validateSetFlag(setValue) {
+    if (!/^[a-zA-Z0-9._[\]-]+=.+$/.test(setValue)) {
+        console.error(`Invalid --set format: ${SecurityUtils.sanitizeLogMessage(setValue)}`);
+        console.error('Expected format: key=value');
+        process.exit(1);
+    }
+}
 async function cmdDeploy(release, namespace, flags) {
     if (!release)
         usageAndExit('Missing <release>');
+    validateReleaseName(release);
     const args = ['upgrade', '--install', release, '.'];
     if (namespace) {
+        validateNamespace(namespace);
         args.push('--namespace', namespace);
     }
     if (flags?.env) {
@@ -256,6 +292,7 @@ async function cmdDeploy(release, namespace, flags) {
     }
     if (flags?.set) {
         for (const setValue of flags.set) {
+            validateSetFlag(setValue);
             args.push('--set', setValue);
         }
     }
@@ -465,7 +502,7 @@ async function cmdUmbrellaAdd(subchartPath, silent = false) {
     fs.mkdirSync(subchartDir, { recursive: true });
     const relativeSubchartPath = path.relative(chartsRoot, subchartDir) || subchartName;
     const normalizedSubchartPath = relativeSubchartPath.split(path.sep).join('/');
-    const chartFile = path.join(subchartDir, 'chart.ts');
+    const chartFile = SecurityUtils.validatePath(path.join(subchartDir, 'chart.ts'), chartsRoot);
     const { generateFlexibleSubchartTemplate } = await import('./lib/templates/flexible-subchart.js');
     const subchartContent = generateFlexibleSubchartTemplate(subchartName);
     fs.writeFileSync(chartFile, subchartContent);
@@ -479,8 +516,9 @@ async function cmdUmbrellaAdd(subchartPath, silent = false) {
     log(`Subchart ${subchartName} added to umbrella at path '${normalizedSubchartPath}'`, silent);
 }
 async function cmdUmbrellaSynth(outDir, flags) {
-    const umbrellaFile = path.join(process.cwd(), UMBRELLA_FILE_NAME);
-    const defaultOutDir = path.join(process.cwd(), 'dist');
+    const cwd = process.cwd();
+    const umbrellaFile = SecurityUtils.validatePath(path.join(cwd, UMBRELLA_FILE_NAME), cwd);
+    const defaultOutDir = SecurityUtils.validatePath(path.join(cwd, 'dist'), cwd);
     if (!fs.existsSync(umbrellaFile)) {
         console.error('umbrella.ts not found. Run `tl umbrella init` first.');
         process.exit(1);
@@ -511,7 +549,8 @@ fs.mkdirSync(output, { recursive: true });
 await Promise.resolve(runner(output, synthOptions));
 console.log('Umbrella chart written to ' + output);
 `;
-    const wrapperFile = path.join(process.cwd(), '.timonel-umbrella-wrapper.mjs');
+    const cwd = process.cwd();
+    const wrapperFile = SecurityUtils.validatePath(path.join(cwd, '.timonel-umbrella-wrapper.mjs'), cwd);
     try {
         fs.writeFileSync(wrapperFile, wrapperScript);
         const result = spawnSync(process.execPath, [TSX_CLI_PATH, wrapperFile], {

package/dist/index.d.ts

@@ -12,5 +12,7 @@ export { DEFAULT_TERMINATION_GRACE_PERIOD, isValidDisruptionBudget, isValidKuber
 export { AWS_HELPERS, createHelper, FILE_ACCESS_HELPERS, formatHelpers, generateHelpersTemplate, getDefaultHelpers, getHelpersByCategory, KUBERNETES_HELPERS, SPRIG_HELPERS, STANDARD_HELPERS, TEMPLATE_FUNCTION_HELPERS, type HelperDefinition, } from './lib/utils/helmHelpers.js';
 export { createLogger, logger, LogLevel, TimonelLogger, type LogContext, type LoggerConfig, } from './lib/utils/logger.js';
 export { UmbrellaRutter } from './lib/umbrellaRutter.js';
-export { helmIf, helmRange, helmWith, helmInclude, helmDefine, helmVar, helmBlock, helmComment, helmFragment, createHelmExpression, isHelmConstruct, isHelmExpression, type HelmConstruct, type HelmExpression, type HelmContent, type HelmWhitespaceOptions, } from './lib/utils/helmControlStructures.js';
+export { helmIf, helmIfSimple, helmRange, helmWith, helmInclude, helmDefine, helmVar, helmBlock, helmComment, helmFragment, createHelmExpression, isHelmConstruct, isHelmExpression, type HelmConstruct, type HelmExpression, type HelmContent, type HelmWhitespaceOptions, } from './lib/utils/helmControlStructures.js';
+export { loadEnvVarsConfig, generateEnvVars, loadAndGenerateEnvVars, type EnvVarConfig, type LoadEnvVarsOptions, } from './lib/utils/envVarsLoader.js';
 export { dumpHelmAwareYaml, validateHelmYaml, type HelmValidationError, type HelmValidationResult, } from './lib/utils/helmYamlSerializer.js';
+export { valuesRef, isHelmValue, isHelmCondition, isHelmFieldConditional, isHelmRange, isHelmWith, serializeHelmValue, serializeHelmCondition, type HelmValue, type HelmCondition, type HelmFieldConditional, type HelmRange, type HelmWith, type HelmHelpers, } from './lib/utils/valuesRef.js';

package/dist/index.js

@@ -9,5 +9,7 @@ export { DEFAULT_TERMINATION_GRACE_PERIOD, isValidDisruptionBudget, isValidKuber
 export { AWS_HELPERS, createHelper, FILE_ACCESS_HELPERS, formatHelpers, generateHelpersTemplate, getDefaultHelpers, getHelpersByCategory, KUBERNETES_HELPERS, SPRIG_HELPERS, STANDARD_HELPERS, TEMPLATE_FUNCTION_HELPERS, } from './lib/utils/helmHelpers.js';
 export { createLogger, logger, LogLevel, TimonelLogger, } from './lib/utils/logger.js';
 export { UmbrellaRutter } from './lib/umbrellaRutter.js';
-export { helmIf, helmRange, helmWith, helmInclude, helmDefine, helmVar, helmBlock, helmComment, helmFragment, createHelmExpression, isHelmConstruct, isHelmExpression, } from './lib/utils/helmControlStructures.js';
+export { helmIf, helmIfSimple, helmRange, helmWith, helmInclude, helmDefine, helmVar, helmBlock, helmComment, helmFragment, createHelmExpression, isHelmConstruct, isHelmExpression, } from './lib/utils/helmControlStructures.js';
+export { loadEnvVarsConfig, generateEnvVars, loadAndGenerateEnvVars, } from './lib/utils/envVarsLoader.js';
 export { dumpHelmAwareYaml, validateHelmYaml, } from './lib/utils/helmYamlSerializer.js';
+export { valuesRef, isHelmValue, isHelmCondition, isHelmFieldConditional, isHelmRange, isHelmWith, serializeHelmValue, serializeHelmCondition, } from './lib/utils/valuesRef.js';

package/dist/lib/helm.js

@@ -36,6 +36,12 @@ export function indent(n, expr) {
         .join('\n');
 }
 export function template(name, context = '.') {
+    if (!isValidHelmPath(name)) {
+        throw new Error(`Invalid template name: ${name}`);
+    }
+    if (!isValidHelmPath(context)) {
+        throw new Error(`Invalid template context: ${context}`);
+    }
     return `{{ template "${name}" ${context} }}`;
 }
 export function include(name, context = '.') {
@@ -157,12 +163,33 @@ export function helmRange(collection, content, options = {}) {
     if (!collection.startsWith('.')) {
         throw new Error('Collection path must start with "." (e.g., ".Values.items")');
     }
+    if (!isValidHelmPath(collection)) {
+        throw new Error(`Invalid collection path: ${collection}`);
+    }
     const { keyValue = false, keyVar = '$key', valueVar = '$value', indexVar = '$index', itemVar = '$item', } = options;
+    const validateVarName = (varName, varType) => {
+        if (!varName.startsWith('$')) {
+            throw new Error(`${varType} must start with $ (e.g., $key, $value)`);
+        }
+        if (!/^\$[a-zA-Z_][a-zA-Z0-9_]*$/.test(varName)) {
+            throw new Error(`Invalid ${varType}: ${varName}`);
+        }
+    };
+    if (keyValue) {
+        validateVarName(keyVar, 'keyVar');
+        validateVarName(valueVar, 'valueVar');
+    }
+    if (options.indexVar !== undefined) {
+        validateVarName(indexVar, 'indexVar');
+    }
+    if (options.itemVar !== undefined) {
+        validateVarName(itemVar, 'itemVar');
+    }
     let rangeExpression;
     if (keyValue) {
         rangeExpression = `{{- range ${keyVar}, ${valueVar} := ${collection} }}`;
     }
-    else if (options.indexVar && options.itemVar) {
+    else if (options.indexVar !== undefined && options.itemVar !== undefined) {
         rangeExpression = `{{- range ${indexVar}, ${itemVar} := ${collection} }}`;
     }
     else {

package/dist/lib/helmChartWriter.js

@@ -2,7 +2,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { SecurityUtils } from './security.js';
 import { createLogger } from './utils/logger.js';
-import { dumpHelmAwareYaml } from './utils/helmYamlSerializer.js';
+import { dumpHelmAwareYaml, postProcessFieldConditionals } from './utils/helmYamlSerializer.js';
 export class HelmChartWriter {
     static write(opts) {
         const { outDir, meta, defaultValues = {}, envValues = {}, assets, helpersTpl, notesTpl, valuesSchema, logger: customLogger, } = opts;
@@ -35,7 +35,8 @@ export class HelmChartWriter {
         timer();
     }
     static createDirectories(outDir) {
-        fs.mkdirSync(path.join(outDir, 'templates'), { recursive: true });
+        const templatesDir = SecurityUtils.validatePath(path.join(outDir, 'templates'), outDir);
+        fs.mkdirSync(templatesDir, { recursive: true });
     }
     static writeChartYaml(outDir, meta) {
         const chartYaml = dumpHelmAwareYaml({
@@ -53,13 +54,16 @@ export class HelmChartWriter {
             icon: meta.icon,
             dependencies: meta.dependencies,
         });
-        fs.writeFileSync(path.join(outDir, 'Chart.yaml'), chartYaml);
+        const chartYamlPath = SecurityUtils.validatePath(path.join(outDir, 'Chart.yaml'), outDir);
+        fs.writeFileSync(chartYamlPath, chartYaml);
     }
     static writeValuesFiles(outDir, defaultValues, envValues) {
-        fs.writeFileSync(path.join(outDir, 'values.yaml'), dumpHelmAwareYaml(defaultValues));
+        const valuesPath = SecurityUtils.validatePath(path.join(outDir, 'values.yaml'), outDir);
+        fs.writeFileSync(valuesPath, dumpHelmAwareYaml(defaultValues));
         for (const [env, values] of Object.entries(envValues)) {
             const sanitizedEnv = SecurityUtils.sanitizeEnvironmentName(env);
-            fs.writeFileSync(path.join(outDir, `values-${sanitizedEnv}.yaml`), dumpHelmAwareYaml(values));
+            const envValuesPath = SecurityUtils.validatePath(path.join(outDir, `values-${sanitizedEnv}.yaml`), outDir);
+            fs.writeFileSync(envValuesPath, dumpHelmAwareYaml(values));
         }
     }
     static writeAssets(outDir, assets) {
@@ -77,20 +81,23 @@ export class HelmChartWriter {
                 .map((h) => [`{{- define "${h.name}" -}}`, h.template.trimEnd(), '{{- end }}', ''].join('\n'))
                 .join('\n');
         }
-        fs.writeFileSync(path.join(outDir, 'templates', '_helpers.tpl'), content);
+        const helpersPath = SecurityUtils.validatePath(path.join(outDir, 'templates', '_helpers.tpl'), outDir);
+        fs.writeFileSync(helpersPath, content);
     }
     static writeNotes(outDir, notesTpl) {
         if (!notesTpl)
             return;
-        fs.writeFileSync(path.join(outDir, 'templates', 'NOTES.txt'), notesTpl.endsWith('\n') ? notesTpl : notesTpl + '\n');
+        const notesPath = SecurityUtils.validatePath(path.join(outDir, 'templates', 'NOTES.txt'), outDir);
+        fs.writeFileSync(notesPath, notesTpl.endsWith('\n') ? notesTpl : notesTpl + '\n');
     }
     static writeSchema(outDir, valuesSchema) {
         if (!valuesSchema)
             return;
-        fs.writeFileSync(path.join(outDir, 'values.schema.json'), JSON.stringify(valuesSchema, null, 2) + '\n');
+        const schemaPath = SecurityUtils.validatePath(path.join(outDir, 'values.schema.json'), outDir);
+        fs.writeFileSync(schemaPath, JSON.stringify(valuesSchema, null, 2) + '\n');
     }
     static writeHelmIgnore(outDir) {
-        const helmIgnorePath = path.join(outDir, '.helmignore');
+        const helmIgnorePath = SecurityUtils.validatePath(path.join(outDir, '.helmignore'), outDir);
         if (!fs.existsSync(helmIgnorePath)) {
             const helmIgnore = [
                 '# VCS',
@@ -149,19 +156,33 @@ function writeSingleAssetFile(outDir, targetDir, directorySegments, fileBaseName
     const chartSubdir = path.join(outDir, targetDir, ...directorySegments);
     SecurityUtils.validatePath(chartSubdir, outDir);
     fs.mkdirSync(chartSubdir, { recursive: true });
+    if (fileBaseName.includes('..') || fileBaseName.includes('/') || fileBaseName.includes('\\')) {
+        throw new Error(`Invalid fileBaseName: ${fileBaseName}`);
+    }
     const filename = `${fileBaseName}.yaml`;
+    if (filename.includes('..') || filename.includes('/') || filename.includes('\\')) {
+        throw new Error(`Invalid filename: ${filename}`);
+    }
     const absolutePath = path.join(chartSubdir, filename);
     SecurityUtils.validatePath(absolutePath, outDir);
-    fs.writeFileSync(absolutePath, yaml.endsWith('\n') ? yaml : `${yaml}\n`);
+    const processedYaml = postProcessFieldConditionals(yaml);
+    fs.writeFileSync(absolutePath, processedYaml.endsWith('\n') ? processedYaml : `${processedYaml}\n`);
 }
 function writeMultipleAssetFiles(outDir, targetDir, directorySegments, fileBaseName, yaml) {
     const chartSubdir = path.join(outDir, targetDir, ...directorySegments);
     SecurityUtils.validatePath(chartSubdir, outDir);
     fs.mkdirSync(chartSubdir, { recursive: true });
-    const parts = splitDocs(yaml);
+    const processedYaml = postProcessFieldConditionals(yaml);
+    const parts = splitDocs(processedYaml);
     parts.forEach((doc, index) => {
+        if (fileBaseName.includes('..') || fileBaseName.includes('/') || fileBaseName.includes('\\')) {
+            throw new Error(`Invalid fileBaseName: ${fileBaseName}`);
+        }
         const suffix = parts.length > 1 ? `-${index + 1}` : '';
         const filename = `${fileBaseName}${suffix}.yaml`;
+        if (filename.includes('..') || filename.includes('/') || filename.includes('\\')) {
+            throw new Error(`Invalid filename: ${filename}`);
+        }
         const absolutePath = path.join(chartSubdir, filename);
         SecurityUtils.validatePath(absolutePath, outDir);
         fs.writeFileSync(absolutePath, doc.endsWith('\n') ? doc : `${doc}\n`);

package/dist/lib/resources/baseResourceProvider.js

@@ -48,6 +48,11 @@ export class BaseResourceProvider {
     createRootLevelApiObject(name, apiVersion, kind, fields, labels, annotations) {
         this.validateKubernetesName(name, kind);
         this.validateLabels(labels, kind);
+        const reservedKeys = ['apiVersion', 'kind', 'metadata'];
+        const conflictingKeys = Object.keys(fields).filter((key) => reservedKeys.includes(key));
+        if (conflictingKeys.length > 0) {
+            throw new Error(`Fields object contains reserved keys: ${conflictingKeys.join(', ')}. These keys cannot be overridden.`);
+        }
         return new ApiObject(this.chart, name, {
             apiVersion,
             kind,

package/dist/lib/resources/cloud/aws/awsResources.js

@@ -120,7 +120,8 @@ export class AWSResources extends BaseResourceProvider {
             throw new Error(`Ingress path "${path}" must start with /`);
         }
         if (normalizedPath.includes('../') || normalizedPath.includes('./')) {
-            console.warn(`Warning: Ingress path "${path}" contains path traversal-like sequences`);
+            const sanitizedPath = path.replace(/[\r\n]/g, '');
+            console.warn(`Warning: Ingress path "${sanitizedPath}" contains path traversal-like sequences`);
         }
     }
     validatePathType(pathType) {