timonel 2.9.0 → 2.9.1

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+## [2.9.1](https://github.com/KenkoGeek/timonel/compare/v2.9.0...v2.9.1) (2025-09-19)
+
+### Bug Fixes
+
+- **deps:** merge conflict solved [skip ci] ([3422464](https://github.com/KenkoGeek/timonel/commit/3422464ddee4a1408019ba4617b6f8e6f6c8fd12))
+- **deps:** upgrade timonel version [skip ci] ([63901ef](https://github.com/KenkoGeek/timonel/commit/63901ef4277a1ebf702fc55337ed1eb7f6b226ea))
+
 # [2.9.0](https://github.com/KenkoGeek/timonel/compare/v2.8.3...v2.9.0) (2025-09-17)
 
 ### Features

package/README.md

@@ -0,0 +1,109 @@
+# Timonel
+
+[![License: MIT][license-badge]][license-url]
+[![npm version][npm-badge]][npm-url]
+[![Security][security-badge]][security-url]
+[![CodeQL][codeql-badge]][codeql-url]
+[![CI][ci-badge]][ci-url]
+[![pnpm][pnpm-badge]][pnpm-url]
+[![Node.js][node-badge]][node-url]
+[![TypeScript][ts-badge]][ts-url]
+[![Maintained by KenkoGeek][maintained-badge]][maintained-url]
+
+Timonel (Spanish for "helmsman") is a TypeScript library to programmatically generate Helm charts
+using cdk8s. Define Kubernetes resources with classes and synthesize a full Helm chart with
+`Chart.yaml`, `values.yaml`, per‑environment values files, and `templates/`.
+
+## ✨ 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.
+- **AWS integrations**:
+  - **AWS**: EBS/EFS StorageClass, ALB Ingress, IRSA ServiceAccount.
+- **Security-first approach** with NetworkPolicies and best practices.
+- **Minimal CLI** (`tl`) for scaffolding and chart generation.
+
+## 🚀 Quick Start
+
+```bash
+# Install Timonel globally
+npm install -g timonel
+
+# Create your first chart
+tl init my-app
+
+# Generate Helm chart
+tl synth charts/my-app charts/my-app-dist
+
+# Use with Helm
+helm install my-app charts/my-app-dist
+```
+
+## 📚 Documentation
+
+## 🔧 Troubleshooting
+
+### CDK8s Module Not Found Error
+
+If you get `Error: Cannot find module 'cdk8s'` when running `tl umbrella synth`:
+
+**Problem**: Timonel is installed globally, but your project needs CDK8s dependencies locally.
+
+**Solution**: Create a `package.json` in your project directory:
+
+```json
+{
+  "name": "my-timonel-project",
+  "version": "1.0.0",
+  "type": "module",
+  "dependencies": {
+    "cdk8s": "^2.70.11",
+    "cdk8s-plus-33": "^2.3.5",
+    "constructs": "^10.4.2",
+    "timonel": "^2.9.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.3.0",
+    "typescript": "^5.9.2"
+  }
+}
+```
+
+Then run:
+
+```bash
+npm install
+tl umbrella synth  # Now it works!
+```
+
+## 🤝 Contributing
+
+See our [Contributing Guide](https://github.com/KenkoGeek/timonel/wiki/Contributing) for development
+setup and guidelines.
+
+## 📄 License
+
+MIT
+
+<!-- Badges -->
+
+[license-badge]: https://img.shields.io/badge/License-MIT-yellow.svg
+[license-url]: https://opensource.org/licenses/MIT
+[npm-badge]: https://img.shields.io/npm/v/timonel.svg
+[npm-url]: https://www.npmjs.com/package/timonel
+[security-badge]: https://img.shields.io/badge/Security-Policy-2ea44f?logo=security&logoColor=fff
+[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-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/
+[maintained-badge]: https://img.shields.io/badge/maintained%20by-KenkoGeek-6C78AF?style=flat
+[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/teast.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

package/dist/cli.js

@@ -37,7 +37,6 @@ function usageAndExit(msg) {
         '  --silent                             Suppress output (useful for CI)',
         '  --env <environment>                  Use environment-specific values',
         '  --set <key=value>                    Override values (can be used multiple times)',
-        '  --version, -v                        Show version information',
         '  --help, -h                           Show this help message',
         '',
         'Examples:',

package/dist/lib/helmChartWriter.js

@@ -5,21 +5,17 @@ import { SecurityUtils } from './security.js';
 export class HelmChartWriter {
     static write(opts) {
         const { outDir, meta, defaultValues = {}, envValues = {}, assets, helpersTpl, notesTpl, valuesSchema, } = opts;
+        console.log(`📝 Writing Helm chart: ${meta.name} v${meta.version} to ${outDir}`);
         const validatedOutDir = SecurityUtils.validatePath(outDir, process.cwd());
-        console.log('📝 Validated outDir:', validatedOutDir);
         this.createDirectories(validatedOutDir);
-        console.log('📝 Directories created');
         this.writeChartYaml(validatedOutDir, meta);
-        console.log('📝 Chart.yaml written');
         this.writeValuesFiles(validatedOutDir, defaultValues, envValues);
-        console.log('📝 Values files written');
         this.writeAssets(validatedOutDir, assets);
-        console.log('📝 Assets written');
         this.writeHelpers(validatedOutDir, helpersTpl);
         this.writeNotes(validatedOutDir, notesTpl);
         this.writeSchema(validatedOutDir, valuesSchema);
         this.writeHelmIgnore(validatedOutDir);
-        console.log('📝 HelmChartWriter.write completed');
+        console.log(`✅ Helm chart written successfully to ${validatedOutDir}`);
     }
     static createDirectories(outDir) {
         fs.mkdirSync(path.join(outDir, 'templates'), { recursive: true });
@@ -112,25 +108,24 @@ function splitDocs(yamlStr) {
         .filter((p) => p.length);
 }
 function writeAssets(outDir, assets) {
-    console.log('🔍 writeAssets called with', assets.length, 'assets');
     for (const asset of assets) {
         const sanitizedId = asset.id.replace(/[^a-zA-Z0-9-_]/g, '');
         if (sanitizedId !== asset.id) {
+            console.error(`❌ Invalid asset ID detected: ${SecurityUtils.sanitizeLogMessage(asset.id)}`);
             throw new Error(`Invalid asset ID: ${SecurityUtils.sanitizeLogMessage(asset.id)}`);
         }
         const targetDir = getTargetDirectory(asset.target);
-        console.log(`🔍 Processing asset: ${asset.id} -> ${sanitizedId}, singleFile: ${asset.singleFile}, target: ${asset.target}`);
-        if (asset.id === 'ingress') {
-            console.log('🔍 Ingress asset YAML preview:', asset.yaml.substring(0, 200));
-            if (asset.yaml.includes('number:')) {
-                console.log('🔍 Ingress contains number field:', asset.yaml.split('\n').filter((line) => line.includes('number:')));
+        try {
+            if (asset.singleFile) {
+                writeSingleAssetFile(outDir, targetDir, sanitizedId, asset.yaml);
+            }
+            else {
+                writeMultipleAssetFiles(outDir, targetDir, sanitizedId, asset.yaml);
             }
         }
-        if (asset.singleFile) {
-            writeSingleAssetFile(outDir, targetDir, sanitizedId, asset.yaml);
-        }
-        else {
-            writeMultipleAssetFiles(outDir, targetDir, sanitizedId, asset.yaml);
+        catch (error) {
+            console.error(`❌ Failed to write asset ${asset.id}:`, error);
+            throw error;
         }
     }
 }

package/dist/lib/rutter.js

@@ -1,7 +1,7 @@
 import { ApiObject, App, Chart, Testing } from 'cdk8s';
 import Handlebars from 'handlebars';
 import YAML from 'yaml';
-import { helm, include } from './helm.js';
+import { include } from './helm.js';
 import { HelmChartWriter } from './helmChartWriter.js';
 import { AWSResources } from './resources/cloud/aws/awsResources.js';
 import { KarpenterResources } from './resources/cloud/aws/karpenterResources.js';
@@ -9,6 +9,7 @@ import { generateHelpersTemplate } from './utils/helmHelpers.js';
 export class Rutter {
     constructor(props) {
         this.assets = [];
+        console.log(`🚀 Initializing Rutter chart: ${props.meta.name} v${props.meta.version}`);
         this.defaultValues = props.defaultValues ?? {};
         this.envValues = props.envValues ?? {};
         this.meta = props.meta;
@@ -140,33 +141,26 @@ export class Rutter {
         });
     }
     validateManifestStructure(manifest) {
-        if (!manifest['apiVersion'] || typeof manifest['apiVersion'] !== 'string') {
-            throw new Error('Kubernetes manifest must have a valid apiVersion');
+        if (!manifest.apiVersion) {
+            console.error('❌ Manifest validation failed: Missing apiVersion');
+            throw new Error('Manifest must have an apiVersion');
         }
-        if (!manifest['kind'] || typeof manifest['kind'] !== 'string') {
-            throw new Error('Kubernetes manifest must have a valid kind');
+        if (!manifest.kind) {
+            console.error('❌ Manifest validation failed: Missing kind');
+            throw new Error('Manifest must have a kind');
         }
-        if (!manifest['metadata'] ||
-            typeof manifest['metadata'] !== 'object' ||
-            manifest['metadata'] === null) {
-            throw new Error('Kubernetes manifest must have valid metadata');
+        if (!manifest.metadata) {
+            console.error('❌ Manifest validation failed: Missing metadata');
+            throw new Error('Manifest must have metadata');
         }
-        const metadata = manifest['metadata'];
-        if (!metadata['name'] || typeof metadata['name'] !== 'string') {
-            throw new Error('Kubernetes manifest metadata must have a valid name');
+        const metadata = manifest.metadata;
+        if (!metadata.name) {
+            console.error('❌ Manifest validation failed: Missing metadata.name');
+            throw new Error('Manifest metadata must have a name');
         }
-        const kind = manifest['kind'];
-        if (kind === 'CustomResourceDefinition') {
-            if (!manifest['spec'] || typeof manifest['spec'] !== 'object' || manifest['spec'] === null) {
-                throw new Error('CustomResourceDefinition must have a valid spec');
-            }
-            const spec = manifest['spec'];
-            if (!spec['group'] || typeof spec['group'] !== 'string') {
-                throw new Error('CustomResourceDefinition spec must have a valid group');
-            }
-            if (!Array.isArray(spec['versions']) || spec['versions'].length === 0) {
-                throw new Error('CustomResourceDefinition must have at least one version in spec.versions');
-            }
+        if (typeof metadata.name !== 'string') {
+            console.error('❌ Manifest validation failed: metadata.name must be a string');
+            throw new Error('Manifest metadata.name must be a string');
         }
     }
     getMeta() {
@@ -182,7 +176,7 @@ export class Rutter {
         return [...this.assets];
     }
     toSynthArray() {
-        console.log('🔍 toSynthArray called');
+        console.log(`📦 Synthesizing chart assets for: ${this.meta.name}`);
         const apiObjectIds = [];
         for (const child of this.chart.node.children) {
             if (child instanceof ApiObject && !child.node.id.endsWith('-placeholder')) {
@@ -198,6 +192,7 @@ export class Rutter {
             }
             return true;
         });
+        console.log(`📋 Found ${manifestObjs.length} manifest objects to process`);
         const enriched = manifestObjs.map((obj) => {
             if (obj && typeof obj === 'object') {
                 const o = obj;
@@ -205,12 +200,12 @@ export class Rutter {
                 o.metadata.labels = o.metadata.labels ?? {};
                 const labels = o.metadata.labels;
                 const defaults = {
-                    'helm.sh/chart': '{{ .Chart.Name }}-{{ .Chart.Version }}',
-                    'app.kubernetes.io/name': include(Rutter.HELPER_NAME),
-                    'app.kubernetes.io/instance': helm.releaseName,
-                    'app.kubernetes.io/version': helm.chartVersion,
+                    'helm.sh/chart': `{{ .Chart.Name }}-{{ .Chart.Version }}`,
+                    'app.kubernetes.io/name': `{{ ${include} "${Rutter.HELPER_NAME}" . }}`,
+                    'app.kubernetes.io/instance': '{{ .Release.Name }}',
+                    'app.kubernetes.io/version': '{{ .Chart.Version }}',
                     'app.kubernetes.io/managed-by': '{{ .Release.Service }}',
-                    'app.kubernetes.io/part-of': helm.chartName,
+                    'app.kubernetes.io/part-of': '{{ .Chart.Name }}',
                 };
                 for (const [key, value] of Object.entries(defaults)) {
                     if (!(key in labels)) {
@@ -221,7 +216,6 @@ export class Rutter {
             return obj;
         });
         const synthAssets = [];
-        console.log('🔍 singleManifestFile:', this.props.singleManifestFile);
         if (this.props.singleManifestFile) {
             const combinedYaml = enriched
                 .map((obj) => this.processHelmTemplates(YAML.stringify(obj).trim()))
@@ -234,7 +228,6 @@ export class Rutter {
             enriched.forEach((obj, index) => {
                 const apiObjectId = apiObjectIds[index];
                 const manifestId = apiObjectId || `manifest-${index + 1}`;
-                console.log(`🔍 Processing asset ${manifestId} (index ${index})`);
                 const yaml = this.processHelmTemplates(YAML.stringify(obj).trim());
                 if (yaml) {
                     synthAssets.push({ id: manifestId, yaml });
@@ -247,15 +240,8 @@ export class Rutter {
         return synthAssets;
     }
     processHelmTemplates(yaml) {
-        console.log('🔍 processHelmTemplates called with YAML length:', yaml.length);
-        if (yaml.includes('{{ .Values.port }}')) {
-            console.log('🎯 Found YAML with port template:');
-            const portIndex = yaml.indexOf('{{ .Values.port }}');
-            console.log(yaml.substring(Math.max(0, portIndex - 50), portIndex + 100));
-        }
         let processed = this.fixCharacterMappingIssues(yaml);
         processed = this.applyHelmTemplateReplacements(processed);
-        console.log('✅ processHelmTemplates completed');
         return processed;
     }
     fixCharacterMappingIssues(yaml) {
@@ -317,38 +303,11 @@ export class Rutter {
         return { nextIndex: j };
     }
     applyHelmTemplateReplacements(processed) {
-        processed = this.fixIncludeStatements(processed);
-        processed = this.fixFunctionCalls(processed);
-        processed = this.fixChartReferences(processed);
-        processed = this.removeHelmExpressionQuotes(processed);
-        if (processed.includes('number:')) {
-            console.log('DEBUG: Before fixConditionalBlocks:', processed.split('\n').filter((line) => line.includes('number:')));
-        }
         processed = this.fixConditionalBlocks(processed);
-        if (processed.includes('number:')) {
-            console.log('DEBUG: After fixConditionalBlocks:', processed.split('\n').filter((line) => line.includes('number:')));
-        }
-        if (processed.includes('number:')) {
-            console.log('DEBUG: Before fixPipeExpressions:', processed.split('\n').filter((line) => line.includes('number:')));
-        }
         processed = this.fixPipeExpressions(processed);
-        if (processed.includes('number:')) {
-            console.log('DEBUG: After fixPipeExpressions:', processed.split('\n').filter((line) => line.includes('number:')));
-        }
-        if (processed.includes('number:')) {
-            console.log('DEBUG: Before fixNestedQuotes:', processed.split('\n').filter((line) => line.includes('number:')));
-        }
         processed = this.fixNestedQuotes(processed);
-        if (processed.includes('number:')) {
-            console.log('DEBUG: After fixNestedQuotes:', processed.split('\n').filter((line) => line.includes('number:')));
-        }
-        if (processed.includes('number:')) {
-            console.log('DEBUG: Before cleanupArtifacts:', processed.split('\n').filter((line) => line.includes('number:')));
-        }
         processed = this.cleanupArtifacts(processed);
-        if (processed.includes('number:')) {
-            console.log('DEBUG: After cleanupArtifacts:', processed.split('\n').filter((line) => line.includes('number:')));
-        }
+        processed = this.removeHelmExpressionQuotes(processed);
         return processed;
     }
     fixIncludeStatements(processed) {
@@ -364,10 +323,6 @@ export class Rutter {
     }
     removeHelmExpressionQuotes(processed) {
         const HELM_EXPRESSION_REPLACEMENT = '$1$2: {{$3}}';
-        console.log('🔧 removeHelmExpressionQuotes called');
-        if (processed.includes('number:')) {
-            console.log('DEBUG: removeHelmExpressionQuotes input contains number:', processed.split('\n').filter((line) => line.includes('number:')));
-        }
         processed = processed.replace(/^(\s*)([^:\s]+):\s*"\{\{([^}]*\|\s*(?:int|float|bool|number)[^}]*)\}\}"/gm, HELM_EXPRESSION_REPLACEMENT);
         processed = processed.replace(/^(\s*)(port):\s*"\{\{([^}]*)\}\}"/gm, HELM_EXPRESSION_REPLACEMENT);
         processed = processed.replace(/^(\s*)(port\.number):\s*"\{\{([^}]*)\}\}"/gm, HELM_EXPRESSION_REPLACEMENT);
@@ -375,23 +330,7 @@ export class Rutter {
         processed = processed.replace(/^(\s*)(backend\.service\.port\.number):\s*"\{\{([^}]*)\}\}"/gm, HELM_EXPRESSION_REPLACEMENT);
         processed = processed.replace(/^(\s*)(spec\.port):\s*"\{\{([^}]*)\}\}"/gm, HELM_EXPRESSION_REPLACEMENT);
         processed = processed.replace(/^(\s*)([^:\s]*\.number):\s*"\{\{([^}]*)\}\}"/gm, HELM_EXPRESSION_REPLACEMENT);
-        const numberMatches = processed.match(/^(\s*)(number):\s*"\{\{([^}]*)\}\}"/gm);
-        if (numberMatches) {
-            console.log('DEBUG: Found number pattern matches:', numberMatches);
-        }
-        else {
-            const anyNumberFields = processed.match(/number:\s*"[^"]*"/gm);
-            if (anyNumberFields) {
-                console.log('DEBUG: Found number fields but regex did not match:', anyNumberFields);
-                const lines = processed.split('\n');
-                const numberLines = lines.filter((line) => line.includes('number:'));
-                console.log('DEBUG: Number field lines:', numberLines);
-            }
-        }
         processed = processed.replace(/^(\s*)(number):\s*"\{\{([^}]*)\}\}"/gm, HELM_EXPRESSION_REPLACEMENT);
-        if (processed.includes('number:')) {
-            console.log('DEBUG: removeHelmExpressionQuotes after number replacement:', processed.split('\n').filter((line) => line.includes('number:')));
-        }
         processed = processed.replace(/^(\s*)(replicas):\s*"\{\{([^}]*)\}\}"/gm, HELM_EXPRESSION_REPLACEMENT);
         processed = processed.replace(/^(\s*)(targetPort):\s*"\{\{([^}]*)\}\}"/gm, HELM_EXPRESSION_REPLACEMENT);
         processed = processed.replace(/^(\s*)(nodePort):\s*"\{\{([^}]*)\}\}"/gm, HELM_EXPRESSION_REPLACEMENT);
@@ -468,8 +407,7 @@ export class Rutter {
         return processed;
     }
     write(outDir) {
-        console.log('🚀 Rutter.write called with outDir:', outDir);
-        console.log('📊 Assets count:', this.assets.length);
+        console.log(`✍️  Writing Helm chart '${this.meta.name}' to: ${outDir}`);
         let helpersContent;
         if (this.props.helpersTpl) {
             if (typeof this.props.helpersTpl === 'string') {
@@ -490,7 +428,7 @@ ${helper.template}
             helpersContent = generateHelpersTemplate(this.props.cloudProvider);
         }
         const synthAssets = this.toSynthArray();
-        console.log('📦 Generated synth assets:', synthAssets.length);
+        console.log(`📄 Generated ${synthAssets.length} assets for chart`);
         HelmChartWriter.write({
             outDir,
             meta: this.meta,
@@ -499,7 +437,7 @@ ${helper.template}
             assets: synthAssets,
             helpersTpl: helpersContent,
         });
-        console.log('✅ Rutter.write completed');
+        console.log(`✅ Helm chart '${this.meta.name}' written successfully`);
     }
 }
 Rutter.HELPER_NAME = 'chart.name';

package/dist/lib/templates/subchart.js

@@ -184,10 +184,7 @@ spec:
         return this.rutter;
     }
     writeHelmChart(outDir) {
-        console.log('🔧 Subchart.writeHelmChart called with outDir:', outDir);
-        console.log('🔧 Rutter instance exists:', !!this.rutter);
         this.rutter.write(outDir);
-        console.log('🔧 Subchart.writeHelmChart completed');
     }
 }
 export function generateSubchart(props = {}, outDir = 'dist') {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "timonel",
   "type": "module",
-  "version": "2.9.0",
+  "version": "2.9.1",
   "description": "Timonel: programmatic Helm chart generator using cdk8s (TypeScript)",
   "bin": {
     "timonel": "dist/cli.js",
@@ -37,13 +37,9 @@
     "deps:update": "pnpm update --latest",
     "md:lint": "markdownlint \"**/*.md\"",
     "md:fix": "markdownlint --fix \"**/*.md\"",
-    "_comment_tests": "ALL TEST SCRIPTS DISABLED TEMPORARILY",
-    "_test": "pnpm test:unit && pnpm test:integration",
-    "_test:unit": "vitest run --config vitest.config.ts",
-    "_test:integration": "vitest run --config vitest.integration.config.ts",
-    "_test:watch": "vitest",
-    "_test:coverage": "vitest run --coverage",
-    "_test:basic-integration": "vitest run tests/integration/basic-chart-generation.int.spec.ts --config vitest.integration.config.ts",
+    "test:integration": "vitest run --config vitest.config.ts",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
     "ci:check": "pnpm typecheck && pnpm lint && pnpm format:check && pnpm build",
     "release": "semantic-release",
     "release:dry": "semantic-release --dry-run",
@@ -89,6 +85,7 @@
     "cdk8s-plus-33": "^2.3.5",
     "constructs": "^10.4.2",
     "handlebars": "^4.7.8",
+    "timonel": "^2.9.0",
     "ts-node": "^10.9.2",
     "yaml": "^2.8.1"
   },