timonel 2.10.2 → 2.11.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+# [2.11.0](https://github.com/KenkoGeek/timonel/compare/v2.10.2...v2.11.0) (2025-09-26)
+
+### Features
+
+- **helm:** add comprehensive helm helpers with Helm template validation ([#123](https://github.com/KenkoGeek/timonel/issues/123)) ([bda8115](https://github.com/KenkoGeek/timonel/commit/bda811546d308eaa3ee5aec7fd8356b4a508940e))
+
 ## [2.10.2](https://github.com/KenkoGeek/timonel/compare/v2.10.1...v2.10.2) (2025-09-20)
 
 ### Bug Fixes

package/README.md

@@ -15,22 +15,18 @@ Helm charts using cdk8s. Define Kubernetes resources with type-safe classes and
 Helm charts with `Chart.yaml`, `values.yaml`, environment-specific values files, and `templates/`
 directory.
 
-> 🚀 **New in v2.9.2**: Enhanced umbrella chart support with flexible subchart templates, improved
-> CLI version handling, and optimized GitHub workflows.
-
 ## ✨ Key Features
 
 - **🔒 Type-safe API** with strict TypeScript and cdk8s constructs
 - **🔧 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
-  - **Azure**: Azure Disk, Azure Files, AKS integrations
-  - **GCP**: GCE Persistent Disk, GKE 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, cdk8s-plus-33, and raw manifests
+- **📦 Flexible subchart templates** supporting cdk8s and cdk8s-plus-33
 
 ## 🚀 Quick Start
 
@@ -246,5 +242,5 @@ MIT
 [maintained-url]: https://github.com/kenkogeek/
 [ci-badge]: https://github.com/KenkoGeek/timonel/actions/workflows/test.yaml/badge.svg?branch=main
 [ci-url]: https://github.com/KenkoGeek/timonel/actions/workflows/test.yaml
-[codeql-badge]: https://github.com/KenkoGeek/timonel/actions/workflows/codeql.yaml/badge.svg
-[codeql-url]: https://github.com/KenkoGeek/timonel/actions/workflows/codeql.yaml
+[codeql-badge]: https://github.com/KenkoGeek/timonel/actions/workflows/codeql.yml/badge.svg
+[codeql-url]: https://github.com/KenkoGeek/timonel/actions/workflows/codeql.yml

package/dist/cli.js

@@ -4,6 +4,7 @@ import fs from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
 import { SecurityUtils } from './lib/security.js';
+import { createLogger } from './lib/utils/logger.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const UMBRELLA_CONFIG_FILE = 'umbrella.config.json';
@@ -43,14 +44,15 @@ function getVersion() {
         return 'unknown';
     }
 }
+const cliLogger = createLogger('cli');
 function log(msg, silent = false) {
     if (!silent) {
-        console.log(msg);
+        cliLogger.info(msg, { operation: 'cli_log' });
     }
 }
 function logError(msg, silent = false) {
     if (!silent) {
-        console.error(SecurityUtils.sanitizeLogMessage(msg));
+        cliLogger.error(msg, { operation: 'cli_error' });
     }
 }
 function usageAndExit(msg, silent = false) {
@@ -80,7 +82,6 @@ function usageAndExit(msg, silent = false) {
             '  --env <environment>                  Use environment-specific values',
             '  --set <key=value>                    Override values (can be used multiple times)',
             '  --help, -h                           Show this help message',
-            '  --version, -v                        Show version information',
             '',
             'Examples:',
             '  tl init my-app',
@@ -104,8 +105,8 @@ async function cmdInit(name, silent = false) {
     const base = path.join(process.cwd(), validName);
     const chartFile = path.join(base, 'chart.ts');
     fs.mkdirSync(base, { recursive: true });
-    const { generateBasicChart } = await import('./lib/templates/basic-chart.js');
-    fs.writeFileSync(chartFile, generateBasicChart(validName));
+    const { generateFlexibleSubchartTemplate } = await import('./lib/templates/flexible-subchart.js');
+    fs.writeFileSync(chartFile, generateFlexibleSubchartTemplate(validName));
     log(`Chart created at ${base}`, silent);
     log(`Generated chart.ts file`, silent);
     log(`Run 'tl synth ${validName}' to generate complete Helm chart`, silent);
@@ -345,8 +346,8 @@ async function cmdUmbrellaAdd(subchartPath, silent = false) {
     const subchartDir = path.join(process.cwd(), 'charts', validSubchartPath);
     fs.mkdirSync(subchartDir, { recursive: true });
     const chartFile = path.join(subchartDir, 'chart.ts');
-    const { generateSubchartTemplate } = await import('./lib/templates/subchart.js');
-    const subchartContent = generateSubchartTemplate(subchartName);
+    const { generateFlexibleSubchartTemplate } = await import('./lib/templates/flexible-subchart.js');
+    const subchartContent = generateFlexibleSubchartTemplate(subchartName);
     fs.writeFileSync(chartFile, subchartContent);
     config.subcharts.push({
         name: subchartName,
@@ -429,13 +430,6 @@ function parseFlags(args) {
                 }
                 break;
             }
-            case '--version':
-            case '-v':
-                if (!flags.silent) {
-                    console.log(`Timonel v${getVersion()}`);
-                }
-                process.exit(0);
-                break;
             case '--help':
             case '-h':
                 usageAndExit(undefined, flags.silent);
@@ -481,12 +475,6 @@ async function main() {
         usageAndExit(undefined, isSilent);
         return;
     }
-    if (args.includes('--version') || args.includes('-v')) {
-        if (!isSilent) {
-            console.log(`Timonel v${getVersion()}`);
-        }
-        process.exit(0);
-    }
     const command = args.shift();
     const flags = parseFlags(args);
     await executeCommand(command, args, flags);

package/dist/index.d.ts

@@ -3,12 +3,11 @@ export * from './lib/helmChartWriter.js';
 export * from './lib/rutter.js';
 export * from './lib/security.js';
 export * from './lib/umbrella.js';
-export { BasicChart } from './lib/templates/basic-chart.js';
 export { FlexibleSubchart, createFlexibleSubchart } from './lib/templates/flexible-subchart.js';
-export { Subchart } from './lib/templates/subchart.js';
 export { UmbrellaChartTemplate as UmbrellaChart } from './lib/templates/umbrella-chart.js';
 export type { ChartProps, SubchartProps } from './lib/types.js';
 export type { AWSALBIngressSpec, AWSEBSStorageClassSpec, AWSEFSStorageClassSpec, AWSIRSAServiceAccountSpec, } from './lib/resources/cloud/aws/awsResources.js';
 export type { KarpenterDisruption, KarpenterDisruptionBudget, KarpenterEC2NodeClassSpec, KarpenterNodeClaimSpec, KarpenterNodePoolSpec, } from './lib/resources/cloud/aws/karpenterResources.js';
 export { DEFAULT_TERMINATION_GRACE_PERIOD, isValidDisruptionBudget, isValidKubernetesDuration, KarpenterVersionUtils, } from './lib/resources/cloud/aws/karpenterResources.js';
 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';

package/dist/index.js

@@ -3,9 +3,8 @@ export * from './lib/helmChartWriter.js';
 export * from './lib/rutter.js';
 export * from './lib/security.js';
 export * from './lib/umbrella.js';
-export { BasicChart } from './lib/templates/basic-chart.js';
 export { FlexibleSubchart, createFlexibleSubchart } from './lib/templates/flexible-subchart.js';
-export { Subchart } from './lib/templates/subchart.js';
 export { UmbrellaChartTemplate as UmbrellaChart } from './lib/templates/umbrella-chart.js';
 export { DEFAULT_TERMINATION_GRACE_PERIOD, isValidDisruptionBudget, isValidKubernetesDuration, KarpenterVersionUtils, } from './lib/resources/cloud/aws/karpenterResources.js';
 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';

package/dist/lib/helmChartWriter.js

@@ -1,11 +1,20 @@
 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';
 export class HelmChartWriter {
     static write(opts) {
         const { outDir, meta, defaultValues = {}, envValues = {}, assets, helpersTpl, notesTpl, valuesSchema, } = opts;
-        console.log(`Writing chart: ${meta.name} v${meta.version} to ${outDir}`);
+        const logger = createLogger('helm-chart-writer');
+        const timer = logger.time('helm_chart_write');
+        logger.info('Starting Helm chart write operation', {
+            chartName: meta.name,
+            version: meta.version,
+            outputDirectory: outDir,
+            assetCount: assets.length,
+            operation: 'helm_write_start',
+        });
         const validatedOutDir = SecurityUtils.validatePath(outDir, process.cwd());
         this.createDirectories(validatedOutDir);
         this.writeChartYaml(validatedOutDir, meta);
@@ -15,7 +24,13 @@ export class HelmChartWriter {
         this.writeNotes(validatedOutDir, notesTpl);
         this.writeSchema(validatedOutDir, valuesSchema);
         this.writeHelmIgnore(validatedOutDir);
-        console.log(`Chart written successfully to ${validatedOutDir}`);
+        logger.info('Helm chart write operation completed successfully', {
+            chartName: meta.name,
+            version: meta.version,
+            outputDirectory: validatedOutDir,
+            operation: 'helm_write_complete',
+        });
+        timer();
     }
     static createDirectories(outDir) {
         fs.mkdirSync(path.join(outDir, 'templates'), { recursive: true });

package/dist/lib/rutter.d.ts

@@ -16,6 +16,7 @@ export declare class Rutter {
     private readonly karpenterResources;
     private readonly meta;
     private readonly props;
+    private readonly logger;
     constructor(props: RutterProps);
     addAWSEBSStorageClass(spec: AWSEBSStorageClassSpec): ApiObject;
     addAWSEFSStorageClass(spec: AWSEFSStorageClassSpec): ApiObject;

package/dist/lib/rutter.js

@@ -3,17 +3,24 @@ import * as jsYaml from 'js-yaml';
 import { include } from './helm.js';
 import { HelmChartWriter } from './helmChartWriter.js';
 import { AWSResources } from './resources/cloud/aws/awsResources.js';
+import { createLogger } from './utils/logger.js';
 import { KarpenterResources } from './resources/cloud/aws/karpenterResources.js';
 import { dumpHelmAwareYaml } from './utils/helmYamlSerializer.js';
 import { generateHelpersTemplate } from './utils/helmHelpers.js';
 export class Rutter {
     constructor(props) {
         this.assets = [];
-        console.log(`Initializing chart: ${props.meta.name} v${props.meta.version}`);
+        this.logger = createLogger('rutter');
         this.defaultValues = props.defaultValues ?? {};
         this.envValues = props.envValues ?? {};
         this.meta = props.meta;
         this.props = props;
+        this.logger.info('Initializing chart', {
+            chartName: props.meta.name,
+            version: props.meta.version,
+            namespace: props.namespace,
+            operation: 'chart_initialization',
+        });
         this.app = new App();
         this.chart = new Chart(this.app, props.meta.name, {
             ...props.chartProps,
@@ -134,24 +141,40 @@ ${yamlContent.trim()}
     }
     validateManifestStructure(manifest) {
         if (!manifest.apiVersion) {
-            console.error('Validation failed: Missing apiVersion');
+            this.logger.error('Validation failed: Missing apiVersion', {
+                operation: 'manifest_validation',
+                issue: 'missing_api_version',
+            });
             throw new Error('Manifest must have an apiVersion');
         }
         if (!manifest.kind) {
-            console.error('Validation failed: Missing kind');
+            this.logger.error('Validation failed: Missing kind', {
+                operation: 'manifest_validation',
+                issue: 'missing_kind',
+            });
             throw new Error('Manifest must have a kind');
         }
         if (!manifest.metadata) {
-            console.error('Validation failed: Missing metadata');
+            this.logger.error('Validation failed: Missing metadata', {
+                operation: 'manifest_validation',
+                issue: 'missing_metadata',
+            });
             throw new Error('Manifest must have metadata');
         }
         const metadata = manifest.metadata;
         if (!metadata.name) {
-            console.error('Validation failed: Missing metadata.name');
+            this.logger.error('Validation failed: Missing metadata.name', {
+                operation: 'manifest_validation',
+                issue: 'missing_metadata_name',
+            });
             throw new Error('Manifest metadata must have a name');
         }
         if (typeof metadata.name !== 'string') {
-            console.error('Validation failed: metadata.name must be a string');
+            this.logger.error('Validation failed: metadata.name must be a string', {
+                operation: 'manifest_validation',
+                issue: 'invalid_metadata_name_type',
+                actual_type: typeof metadata.name,
+            });
             throw new Error('Manifest metadata.name must be a string');
         }
     }
@@ -168,7 +191,11 @@ ${yamlContent.trim()}
         return [...this.assets];
     }
     toSynthArray() {
-        console.log(`Synthesizing chart assets for: ${this.meta.name}`);
+        const timer = this.logger.time('chart_synthesis');
+        this.logger.debug('Starting chart synthesis', {
+            chartName: this.meta.name,
+            operation: 'synthesis_start',
+        });
         const apiObjectIds = [];
         for (const child of this.chart.node.children) {
             if (child instanceof ApiObject && !child.node.id.endsWith('-placeholder')) {
@@ -184,7 +211,12 @@ ${yamlContent.trim()}
             }
             return true;
         });
-        console.log(`Found ${manifestObjs.length} manifest objects to process`);
+        this.logger.info('Processing manifest objects', {
+            chartName: this.meta.name,
+            manifestCount: manifestObjs.length,
+            apiObjectCount: apiObjectIds.length,
+            operation: 'manifest_processing',
+        });
         const enriched = manifestObjs.map((obj) => {
             if (obj && typeof obj === 'object') {
                 const o = obj;
@@ -229,6 +261,13 @@ ${yamlContent.trim()}
         this.assets.forEach((asset) => {
             synthAssets.push({ id: asset.id, yaml: asset.yaml });
         });
+        this.logger.info('Chart synthesis completed', {
+            chartName: this.meta.name,
+            totalAssets: synthAssets.length,
+            additionalAssets: this.assets.length,
+            operation: 'synthesis_complete',
+        });
+        timer();
         return synthAssets;
     }
     processHelmTemplates(yaml) {
@@ -399,7 +438,12 @@ ${yamlContent.trim()}
         return processed;
     }
     write(outDir) {
-        console.log(`Writing chart '${this.meta.name}' to: ${outDir}`);
+        const timer = this.logger.time('chart_write');
+        this.logger.info('Starting chart write operation', {
+            chartName: this.meta.name,
+            outputDirectory: outDir,
+            operation: 'chart_write_start',
+        });
         let helpersContent;
         if (this.props.helpersTpl) {
             if (typeof this.props.helpersTpl === 'string') {
@@ -420,7 +464,11 @@ ${helper.template}
             helpersContent = generateHelpersTemplate(this.props.cloudProvider);
         }
         const synthAssets = this.toSynthArray();
-        console.log(`Generated ${synthAssets.length} assets for chart`);
+        this.logger.info('Generated assets for chart', {
+            chartName: this.meta.name,
+            assetCount: synthAssets.length,
+            operation: 'assets_generated',
+        });
         HelmChartWriter.write({
             outDir,
             meta: this.meta,
@@ -429,7 +477,12 @@ ${helper.template}
             assets: synthAssets,
             helpersTpl: helpersContent,
         });
-        console.log(`Chart '${this.meta.name}' written successfully`);
+        this.logger.info('Chart write operation completed successfully', {
+            chartName: this.meta.name,
+            outputDirectory: outDir,
+            operation: 'chart_write_complete',
+        });
+        timer();
     }
 }
 Rutter.HELPER_NAME = 'chart.name';

package/dist/lib/templates/flexible-subchart.d.ts

@@ -25,3 +25,4 @@ export declare function createFlexibleSubchart(scope: Chart, id: string, config:
     description?: string;
     [key: string]: unknown;
 }): FlexibleSubchart;
+export declare function generateFlexibleSubchartTemplate(name: string): string;

package/dist/lib/templates/flexible-subchart.js

@@ -105,3 +105,104 @@ export class FlexibleSubchart extends Chart {
 export function createFlexibleSubchart(scope, id, config) {
     return new FlexibleSubchart(scope, id, config);
 }
+export function generateFlexibleSubchartTemplate(name) {
+    return `import { App } from 'cdk8s';
+import { Rutter } from 'timonel';
+
+/**
+ * Creates a new chart with simple Rutter implementation
+ * @returns Rutter instance for Helm chart generation
+ * @since 2.11.0
+ */
+export default function createChart() {
+  const app = new App({ outdir: 'dist' });
+  
+  const rutter = new Rutter({
+    meta: { 
+      name: '${name}', 
+      version: '1.0.0',
+      description: '${name} subchart'
+    },
+    scope: app,
+    defaultValues: {
+      appName: '${name}',
+      image: 'nginx:latest',
+      port: 80,
+      replicas: 1,
+    },
+  });
+
+  // Add simple deployment
+  rutter.addManifest({
+    apiVersion: 'apps/v1',
+    kind: 'Deployment',
+    metadata: { 
+      name: '${name}',
+      labels: {
+        'app.kubernetes.io/name': '${name}'
+      }
+    },
+    spec: {
+      replicas: 1,
+      selector: {
+        matchLabels: {
+          'app.kubernetes.io/name': '${name}'
+        }
+      },
+      template: {
+        metadata: {
+          labels: {
+            'app.kubernetes.io/name': '${name}'
+          }
+        },
+        spec: {
+          containers: [{
+            name: '${name}',
+            image: 'nginx:latest',
+            ports: [{
+              containerPort: 80
+            }],
+            env: [
+              { name: 'APP_NAME', value: '${name}' },
+              { name: 'PORT', value: '80' }
+            ]
+          }]
+        }
+      }
+    }
+  }, 'deployment');
+
+  // Add Service
+  rutter.addManifest({
+    apiVersion: 'v1',
+    kind: 'Service',
+    metadata: {
+      name: '${name}',
+      labels: {
+        'app.kubernetes.io/name': '${name}'
+      }
+    },
+    spec: {
+      type: 'ClusterIP',
+      ports: [{
+        port: 80,
+        targetPort: 80,
+        protocol: 'TCP',
+        name: 'http'
+      }],
+      selector: {
+        'app.kubernetes.io/name': '${name}'
+      }
+    }
+  }, 'service');
+
+  return rutter;
+}
+
+// Auto-execute when run directly
+if (import.meta.url === new URL(import.meta.url).href) {
+  const chart = createChart();
+  chart.write('dist');
+}
+`;
+}

package/dist/lib/templates/umbrella-chart.d.ts

@@ -1,5 +1,4 @@
-import type { App } from 'cdk8s';
-import { Chart } from 'cdk8s';
+import { App, Chart } from 'cdk8s';
 import type { ChartProps } from '../types.js';
 export declare function generateUmbrellaChart(name: string): string;
 export declare class UmbrellaChartTemplate extends Chart {
@@ -9,6 +8,18 @@ export declare class UmbrellaChartTemplate extends Chart {
     private configure;
     private _addService;
     private _addSubchart;
+    private _createFlexibleSubchart;
+    private _createFallbackSubchart;
+    private _handleFunctionChart;
+    private _handleObjectChart;
+    private _isRutterInstance;
+    private _isChartInstance;
+    private _processRutterInstance;
+    private _processChartInstance;
+    private _copyTemplates;
+    private _ensureDirectoryExists;
+    private _processAssets;
+    private _cleanupTempDir;
     private _createBasicSubchart;
     writeHelmChart(outputDir: string): void;
 }