timonel 2.11.0 → 2.12.1

package/CHANGELOG.md

@@ -1,3 +1,20 @@
+## [2.12.1](https://github.com/KenkoGeek/timonel/compare/v2.12.0...v2.12.1) (2025-09-28)
+
+### Bug Fixes
+
+- **cli:** new feature for cli ([a8c5326](https://github.com/KenkoGeek/timonel/commit/a8c532617616bfedada20d28bcc4fe94ea165321))
+
+# [2.12.0](https://github.com/KenkoGeek/timonel/compare/v2.11.0...v2.12.0) (2025-09-28)
+
+### Bug Fixes
+
+- **cli:** harden flag handling and path validation ([#130](https://github.com/KenkoGeek/timonel/issues/130)) ([2186d88](https://github.com/KenkoGeek/timonel/commit/2186d886428752025e7bf531c4a6541dade683a6))
+
+### Features
+
+- **docs:** update references and CLI [skip ci] ([23704d3](https://github.com/KenkoGeek/timonel/commit/23704d3164cfbb92d183af40c70e27a32b566d06))
+- **docs:** update references and CLI [skip ci] ([be4bcdc](https://github.com/KenkoGeek/timonel/commit/be4bcdca62cb3a9339e5ad70efc0ba31a6d9d5be))
+
 # [2.11.0](https://github.com/KenkoGeek/timonel/compare/v2.10.2...v2.11.0) (2025-09-26)
 
 ### Features

package/README.md

@@ -38,9 +38,6 @@ npm install -g timonel
 
 # Or use with pnpm
 pnpm add -g timonel
-
-# Verify installation
-tl --version
 ```
 
 ### Basic Usage
@@ -140,6 +137,8 @@ export const umbrella = new UmbrellaChartTemplate(umbrellaConfig);
   patterns and practices
 - **[Contributing](https://github.com/KenkoGeek/timonel/wiki/Contributing)** - Development setup
   and guidelines
+- **[Timonel Examples Repository](https://github.com/KenkoGeek/timonel-examples)** - Curated
+  collection of ready-to-run Timonel sample projects
 
 ## 🔧 Troubleshooting
 
@@ -157,10 +156,10 @@ If you get `Error: Cannot find module 'cdk8s'` when running `tl umbrella synth`:
   "version": "1.0.0",
   "type": "module",
   "dependencies": {
-    "cdk8s": "^2.70.15",
-    "cdk8s-plus-33": "^2.3.6",
+    "cdk8s": "^2.70.16",
+    "cdk8s-plus-33": "^2.3.8",
     "constructs": "^10.4.2",
-    "timonel": "^2.9.2"
+    "timonel": "^2.11.0"
   },
   "devDependencies": {
     "@types/node": "^24.5.2",
@@ -176,45 +175,6 @@ npm install
 tl umbrella synth  # Now it works!
 ```
 
-### Version Display Issues
-
-If the CLI shows an incorrect version:
-
-**Problem**: The CLI might be using cached or hardcoded version information.
-
-**Solution**: Rebuild the project:
-
-```bash
-# In the Timonel project directory
-pnpm build
-tl --version  # Should show correct version
-```
-
-### TypeScript Compilation Errors
-
-If you encounter TypeScript errors when using umbrella charts:
-
-**Problem**: Type mismatches in subchart configurations.
-
-**Solution**: Ensure proper type casting for version and description fields:
-
-```typescript
-// ✅ Correct
-const subchart = {
-  name: 'my-service',
-  version: '1.0.0' as string,
-  description: 'My service' as string,
-  chart: myChartFunction,
-};
-
-// ❌ Incorrect
-const subchart = {
-  name: 'my-service',
-  version: someUnknownValue, // This will cause TypeScript errors
-  chart: myChartFunction,
-};
-```
-
 ## 🤝 Contributing
 
 See our [Contributing Guide](https://github.com/KenkoGeek/timonel/wiki/Contributing) for development

package/dist/cli.js

@@ -12,37 +12,20 @@ const UMBRELLA_FILE_NAME = 'umbrella.ts';
 const PACKAGE_JSON_FILE = 'package.json';
 function getVersion() {
     try {
-        const possiblePaths = [
-            path.resolve(__dirname, '..', PACKAGE_JSON_FILE),
-            path.resolve(__dirname, '..', '..', PACKAGE_JSON_FILE),
-            path.resolve(process.cwd(), PACKAGE_JSON_FILE),
-            path.resolve(__dirname, PACKAGE_JSON_FILE),
-        ];
-        for (const packagePath of possiblePaths) {
-            try {
-                const validatedPath = SecurityUtils.validatePath(packagePath, process.cwd());
-                if (fs.existsSync(validatedPath)) {
-                    try {
-                        const packageJson = JSON.parse(fs.readFileSync(validatedPath, 'utf8'));
-                        return packageJson.version || 'unknown';
-                    }
-                    catch {
-                        continue;
-                    }
-                }
-            }
-            catch {
-                continue;
-            }
+        const packagePath = path.resolve(__dirname, '..', PACKAGE_JSON_FILE);
+        const allowedBase = path.resolve(__dirname, '..');
+        const validatedPath = SecurityUtils.validatePath(packagePath, allowedBase);
+        const packageJson = JSON.parse(fs.readFileSync(validatedPath, 'utf8'));
+        if (packageJson.version) {
+            return packageJson.version;
         }
-        if (process.env.npm_package_version) {
-            return process.env.npm_package_version;
-        }
-        return 'unknown';
     }
     catch {
-        return 'unknown';
     }
+    if (process.env.npm_package_version) {
+        return process.env.npm_package_version;
+    }
+    return 'unknown';
 }
 const cliLogger = createLogger('cli');
 function log(msg, silent = false) {
@@ -81,6 +64,7 @@ function usageAndExit(msg, silent = false) {
             '  --silent                             Suppress output (useful for CI)',
             '  --env <environment>                  Use environment-specific values',
             '  --set <key=value>                    Override values (can be used multiple times)',
+            '  --mode <dependencies|inline>         Umbrella synth mode (default: dependencies)',
             '  --help, -h                           Show this help message',
             '',
             'Examples:',
@@ -162,7 +146,23 @@ await import(pathToFileURL('${tempChartFile}').href);
     }
 }
 async function cmdValidate(flags) {
-    const result = spawnSync('helm', ['lint', '.'], {
+    const lintArgs = ['lint', '.'];
+    if (flags?.env) {
+        try {
+            const sanitizedEnv = SecurityUtils.sanitizeEnvironmentName(flags.env);
+            lintArgs.push('-f', `values-${sanitizedEnv}.yaml`);
+        }
+        catch (error) {
+            console.error(SecurityUtils.sanitizeLogMessage(error.message));
+            process.exit(1);
+        }
+    }
+    if (flags?.set) {
+        for (const setValue of flags.set) {
+            lintArgs.push('--set', setValue);
+        }
+    }
+    const result = spawnSync('helm', lintArgs, {
         stdio: flags?.silent ? 'pipe' : 'inherit',
         encoding: 'utf8',
     });
@@ -180,6 +180,21 @@ async function cmdDeploy(release, namespace, flags) {
     if (namespace) {
         args.push('--namespace', namespace);
     }
+    if (flags?.env) {
+        try {
+            const sanitizedEnv = SecurityUtils.sanitizeEnvironmentName(flags.env);
+            args.push('-f', `values-${sanitizedEnv}.yaml`);
+        }
+        catch (error) {
+            console.error(SecurityUtils.sanitizeLogMessage(error.message));
+            process.exit(1);
+        }
+    }
+    if (flags?.set) {
+        for (const setValue of flags.set) {
+            args.push('--set', setValue);
+        }
+    }
     const result = spawnSync('helm', args.filter((arg) => Boolean(arg)), {
         stdio: flags?.silent ? 'pipe' : 'inherit',
         encoding: 'utf8',
@@ -220,18 +235,22 @@ async function cmdTemplates(flags) {
         });
     }
 }
+const UMBRELLA_SYNTH_MODES = ['dependencies', 'inline'];
 async function cmdUmbrella(subcommand, args, flags) {
     if (!subcommand)
         usageAndExit('Missing umbrella subcommand');
+    const workingArgs = [...(args ?? [])];
+    const subcommandFlags = parseFlags(workingArgs);
+    const mergedFlags = mergeCliFlags(flags, subcommandFlags);
     switch (subcommand) {
         case 'init':
-            await cmdUmbrellaInit(args?.[0], flags?.silent);
+            await cmdUmbrellaInit(workingArgs[0], mergedFlags.silent);
             break;
         case 'add':
-            await cmdUmbrellaAdd(args?.[0], flags?.silent);
+            await cmdUmbrellaAdd(workingArgs[0], mergedFlags.silent);
             break;
         case 'synth':
-            await cmdUmbrellaSynth(args?.[0], flags);
+            await cmdUmbrellaSynth(workingArgs[0], mergedFlags);
             break;
         default:
             usageAndExit(`Unknown umbrella subcommand: ${subcommand}`);
@@ -290,28 +309,54 @@ function addImportStatement(content, importStatement) {
     return lines.join('\n');
 }
 function buildSubchartsContent(subchartsContent, subchartEntry) {
-    const hasExistingEntries = /\{\s*name:\s*['"]/.test(subchartsContent || '');
-    if (!hasExistingEntries) {
-        return `\n    // Add your subcharts here:\n    ${subchartEntry},\n  `;
-    }
-    const trimmedContent = subchartsContent?.trimEnd() ?? '';
-    const needsComma = !trimmedContent.endsWith(',');
-    const comma = needsComma ? ',' : '';
-    return trimmedContent + `${comma}\n    ${subchartEntry}`;
+    const existingEntries = (subchartsContent || '')
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => line && !line.startsWith('//'))
+        .map((line) => line.replace(/,$/, ''));
+    if (existingEntries.includes(subchartEntry)) {
+        return subchartsContent ?? '';
+    }
+    const entries = [...existingEntries, subchartEntry];
+    const lines = ['  // Add your subcharts here:'];
+    for (const entry of entries) {
+        lines.push(`  ${entry},`);
+    }
+    return `\n${lines.join('\n')}\n`;
 }
 function addSubchartToArray(content, chartName, camelCaseName) {
-    const subchartsRegex = /subcharts:\s*\[([\s\S]*?)\]/;
+    const subchartsRegex = /(const SUBCHARTS[\s\S]*?=\s*\[)([\s\S]*?)(\];)/;
     const match = content.match(subchartsRegex);
     if (!match) {
         return content;
     }
-    const subchartsContent = match[1];
-    if (subchartsContent?.includes(`name: '${chartName}'`)) {
+    const [, prefix, body, suffix] = match;
+    if (body?.includes(`name: '${chartName}'`)) {
         return content;
     }
-    const subchartEntry = `{ name: '${chartName}', chart: ${camelCaseName} }`;
-    const newSubchartsContent = buildSubchartsContent(subchartsContent, subchartEntry);
-    return content.replace(subchartsRegex, `subcharts: [${newSubchartsContent}\n  ]`);
+    const subchartEntry = `{ name: '${chartName}', factory: ${camelCaseName} }`;
+    const newBody = buildSubchartsContent(body, subchartEntry);
+    return content.replace(subchartsRegex, `${prefix}${newBody}${suffix}`);
+}
+function mergeCliFlags(base, override) {
+    const merged = { ...(base || {}) };
+    if (!override) {
+        return merged;
+    }
+    if (override.dryRun !== undefined)
+        merged.dryRun = override.dryRun;
+    if (override.silent !== undefined)
+        merged.silent = override.silent;
+    if (override.env !== undefined)
+        merged.env = override.env;
+    if (override.mode !== undefined)
+        merged.mode = override.mode;
+    const baseSet = base?.set ?? [];
+    const overrideSet = override.set ?? [];
+    if (baseSet.length || overrideSet.length) {
+        merged.set = [...baseSet, ...overrideSet];
+    }
+    return merged;
 }
 function updateUmbrellaTs(subchartPath, chartName) {
     const umbrellaFile = path.join(process.cwd(), UMBRELLA_FILE_NAME);
@@ -343,8 +388,19 @@ async function cmdUmbrellaAdd(subchartPath, silent = false) {
     }
     const config = JSON.parse(fs.readFileSync(configFile, 'utf8'));
     const subchartName = path.basename(validSubchartPath);
-    const subchartDir = path.join(process.cwd(), 'charts', validSubchartPath);
+    const chartsRoot = path.join(process.cwd(), 'charts');
+    const targetSubchartPath = path.join(chartsRoot, validSubchartPath);
+    let subchartDir;
+    try {
+        subchartDir = SecurityUtils.validatePath(targetSubchartPath, chartsRoot);
+    }
+    catch (error) {
+        console.error(SecurityUtils.sanitizeLogMessage(error.message));
+        process.exit(1);
+    }
     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 { generateFlexibleSubchartTemplate } = await import('./lib/templates/flexible-subchart.js');
     const subchartContent = generateFlexibleSubchartTemplate(subchartName);
@@ -352,11 +408,11 @@ async function cmdUmbrellaAdd(subchartPath, silent = false) {
     config.subcharts.push({
         name: subchartName,
         version: getVersion(),
-        path: `./charts/${validSubchartPath}/chart.ts`,
+        path: `./charts/${normalizedSubchartPath}/chart.ts`,
     });
     fs.writeFileSync(configFile, JSON.stringify(config, null, 2));
-    updateUmbrellaTs(validSubchartPath, subchartName);
-    log(`Subchart ${subchartName} added to umbrella at path '${validSubchartPath}'`, silent);
+    updateUmbrellaTs(normalizedSubchartPath, subchartName);
+    log(`Subchart ${subchartName} added to umbrella at path '${normalizedSubchartPath}'`, silent);
 }
 async function cmdUmbrellaSynth(outDir, flags) {
     const umbrellaFile = path.join(process.cwd(), UMBRELLA_FILE_NAME);
@@ -366,9 +422,13 @@ async function cmdUmbrellaSynth(outDir, flags) {
         process.exit(1);
     }
     const resolvedOutDir = outDir ? path.resolve(outDir) : defaultOutDir;
-    await executeTypeScriptUmbrella(umbrellaFile, resolvedOutDir, flags);
+    const synthMode = flags?.mode ?? 'dependencies';
+    if (!UMBRELLA_SYNTH_MODES.includes(synthMode)) {
+        usageAndExit('Invalid mode. Use "dependencies" or "inline".', flags?.silent);
+    }
+    await executeTypeScriptUmbrella(umbrellaFile, resolvedOutDir, synthMode, flags);
 }
-async function executeTypeScriptUmbrella(resolvedPath, outDir, flags) {
+async function executeTypeScriptUmbrella(resolvedPath, outDir, mode, flags) {
     const wrapperScript = `
 import { pathToFileURL } from 'url';
 
@@ -380,9 +440,10 @@ if (typeof runner !== 'function') {
 }
 
 const output = '${outDir}';
+const synthOptions = { mode: '${mode}' };
 const fs = await import('fs');
 fs.mkdirSync(output, { recursive: true });
-await Promise.resolve(runner(output));
+await Promise.resolve(runner(output, synthOptions));
 console.log('Umbrella chart written to ' + output);
 `;
     const wrapperFile = path.join(process.cwd(), '.timonel-umbrella-wrapper.mjs');
@@ -430,6 +491,14 @@ function parseFlags(args) {
                 }
                 break;
             }
+            case '--mode': {
+                const modeValue = args.shift();
+                if (!modeValue || !UMBRELLA_SYNTH_MODES.includes(modeValue)) {
+                    usageAndExit('Invalid mode. Use "dependencies" or "inline".', flags.silent);
+                }
+                flags.mode = modeValue;
+                break;
+            }
             case '--help':
             case '-h':
                 usageAndExit(undefined, flags.silent);

package/dist/lib/templates/umbrella-chart.js

@@ -7,36 +7,152 @@ import { generateHelpersTemplate } from '../utils/helmHelpers.js';
 import { createFlexibleSubchart } from './flexible-subchart.js';
 export function generateUmbrellaChart(name) {
     return `import { App } from 'cdk8s';
-import { UmbrellaChart } from 'timonel';
+import { Rutter } from 'timonel';
+import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import * as jsYaml from 'js-yaml';
 // Import subcharts - add your subchart imports here
 
-/**
- * Synthesizes the umbrella chart with all subcharts
- * @param outDir Output directory for generated charts
- * @since 2.11.0
- */
-export function synth(outDir: string) {
+type SynthMode = 'dependencies' | 'inline';
+
+interface SynthOptions {
+  mode?: SynthMode;
+}
+
+const DEFAULT_MODE: SynthMode = 'dependencies';
+
+const SUBCHARTS: Array<{ name: string; factory: () => Rutter }> = [
+  // Add your subcharts here:
+  // { name: 'my-subchart', factory: mySubchart },
+];
+
+function resolveMode(options?: SynthOptions): SynthMode {
+  const explicit = options?.mode;
+  if (explicit === 'dependencies' || explicit === 'inline') {
+    return explicit;
+  }
+  const envMode = process.env.TIMONEL_UMBRELLA_MODE;
+  if (envMode === 'dependencies' || envMode === 'inline') {
+    return envMode;
+  }
+  return DEFAULT_MODE;
+}
+
+function readYamlFile(filePath: string): Record<string, unknown> {
+  if (!existsSync(filePath)) {
+    return {};
+  }
+  const content = jsYaml.load(readFileSync(filePath, 'utf8'));
+  return content && typeof content === 'object' ? (content as Record<string, unknown>) : {};
+}
+
+export function synth(outDir: string, options?: SynthOptions) {
+  const mode = resolveMode(options);
   const app = new App({
     outdir: outDir,
     outputFileExtension: '.yaml',
-    yamlOutputType: 'FILE_PER_RESOURCE'
+    yamlOutputType: 'FILE_PER_RESOURCE',
   });
 
-  const chart = new UmbrellaChart(app, '${name}', {
-    name: '${name}',
-    version: '0.1.0',
-    description: '${name} umbrella chart',
-    services: [],
-    subcharts: [
-      // Add your subcharts here:
-    ]
+  const umbrella = new Rutter({
+    meta: {
+      name: '${name}',
+      version: '0.1.0',
+      description: '${name} umbrella chart',
+      appVersion: '1.0.0',
+      type: 'application',
+    },
+    scope: app,
+    defaultValues: {
+      namespace: 'default',
+      createNamespace: false,
+    },
   });
 
-  // Generate Helm chart files
-  chart.writeHelmChart(outDir);
-  
-  // Also generate CDK8s YAML files
+  umbrella.addConditionalManifest(
+    {
+      apiVersion: 'v1',
+      kind: 'Namespace',
+      metadata: {
+        name: '{{ .Values.namespace | default .Release.Namespace }}',
+      },
+    },
+    'createNamespace',
+    'namespace',
+  );
+
+  umbrella.write(outDir);
+
+  const chartPath = join(outDir, 'Chart.yaml');
+  const valuesPath = join(outDir, 'values.yaml');
+  const templatesDir = join(outDir, 'templates');
+  mkdirSync(templatesDir, { recursive: true });
+
+  const chartDoc = readYamlFile(chartPath);
+  const valuesDoc = readYamlFile(valuesPath);
+
+  if (mode === 'dependencies') {
+    const chartsDir = join(outDir, 'charts');
+    mkdirSync(chartsDir, { recursive: true });
+
+    const dependencies: Array<{ name: string; version: string; repository: string }> = [];
+
+    SUBCHARTS.forEach((subchart) => {
+      const instance = subchart.factory();
+      const targetDir = join(chartsDir, subchart.name);
+      rmSync(targetDir, { recursive: true, force: true });
+      instance.write(targetDir);
+      const meta = instance.getMeta();
+      const version = meta.version ?? '0.1.0';
+      dependencies.push({
+        name: subchart.name,
+        version,
+        repository: 'file://./charts/' + subchart.name,
+      });
+      const subchartValues = readYamlFile(join(targetDir, 'values.yaml'));
+      if (Object.keys(subchartValues).length > 0) {
+        valuesDoc[subchart.name] = subchartValues;
+      }
+    });
+
+    chartDoc.dependencies = dependencies;
+  } else {
+    const chartsDir = join(outDir, 'charts');
+    if (existsSync(chartsDir)) {
+      rmSync(chartsDir, { recursive: true, force: true });
+    }
+    delete chartDoc.dependencies;
+
+    SUBCHARTS.forEach((subchart) => {
+      const instance = subchart.factory();
+      const tempDir = join(outDir, '.timonel-inline-' + subchart.name);
+      rmSync(tempDir, { recursive: true, force: true });
+      instance.write(tempDir);
+
+      const subTemplatesDir = join(tempDir, 'templates');
+      if (existsSync(subTemplatesDir)) {
+        const targetTemplatesDir = join(templatesDir, subchart.name);
+        mkdirSync(targetTemplatesDir, { recursive: true });
+        for (const file of readdirSync(subTemplatesDir)) {
+          copyFileSync(join(subTemplatesDir, file), join(targetTemplatesDir, file));
+        }
+      }
+
+      const subchartValues = readYamlFile(join(tempDir, 'values.yaml'));
+      if (Object.keys(subchartValues).length > 0) {
+        valuesDoc[subchart.name] = subchartValues;
+      }
+
+      rmSync(tempDir, { recursive: true, force: true });
+    });
+  }
+
+  writeFileSync(chartPath, jsYaml.dump(chartDoc));
+  writeFileSync(valuesPath, jsYaml.dump(valuesDoc));
+
   app.synth();
+
+  console.log('✅ Umbrella chart generated in ' + mode + ' mode!');
 }
 
 // Auto-execute when run directly

package/dist/lib/utils/helmYamlSerializer.js

@@ -217,7 +217,7 @@ function isQuotesBalanced(str) {
 function validateFunctionCalls(_content) {
 }
 function checkCommonIssues(yaml, warnings) {
-    const deprecatedFunctions = ['template', 'default'];
+    const deprecatedFunctions = ['template'];
     for (const func of deprecatedFunctions) {
         const pattern = new RegExp(`\\{\\{[^}]*\\b${func}\\b[^}]*\\}\\}`, 'g');
         let match;
@@ -232,7 +232,7 @@ function checkCommonIssues(yaml, warnings) {
     }
 }
 function checkQuotedExpressions(yaml, warnings) {
-    const quotedPatterns = [/'\(\\{\\{[^}]+\\}\\}\)'/g, /"\(\\{\\{[^}]+\\}\\}\)"/g];
+    const quotedPatterns = [/'(\{\{[^}]+\}\})'/g, /"(\{\{[^}]+\}\})"/g];
     for (const pattern of quotedPatterns) {
         let match;
         pattern.lastIndex = 0;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "timonel",
   "type": "module",
-  "version": "2.11.0",
+  "version": "2.12.1",
   "description": "Timonel: programmatic Helm chart generator using cdk8s (TypeScript)",
   "bin": {
     "timonel": "dist/cli.js",