timonel 2.12.0 → 2.12.2-beta.1

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [2.12.2-beta.1](https://github.com/KenkoGeek/timonel/compare/v2.12.1...v2.12.2-beta.1) (2025-10-04)
+
+### Bug Fixes
+
+- **cli:** handle flags after positional arguments ([#142](https://github.com/KenkoGeek/timonel/issues/142)) ([36ac024](https://github.com/KenkoGeek/timonel/commit/36ac024fa7c2a454a184394337a65ebae46a65f9))
+
+## [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

package/README.md

@@ -137,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
 

package/dist/cli.js

@@ -3,10 +3,66 @@ import { spawnSync } from 'child_process';
 import fs from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
+import { createRequire } from 'module';
 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 esmRequire = createRequire(import.meta.url);
+function getLocalTsxCliPath() {
+    try {
+        return esmRequire.resolve('tsx/cli');
+    }
+    catch (error) {
+        const sanitizedMessage = SecurityUtils.sanitizeLogMessage('Unable to locate the local tsx CLI module required to execute commands.');
+        console.error(sanitizedMessage);
+        if (error instanceof Error && error.message) {
+            console.error(SecurityUtils.sanitizeLogMessage(error.message));
+        }
+        process.exit(1);
+    }
+}
+function escapeForSingleQuotedLiteral(value) {
+    return value
+        .replace(/\\/g, '\\\\')
+        .replace(/'/g, "\\'")
+        .replace(/\r/g, '\\r')
+        .replace(/\n/g, '\\n')
+        .replace(/\t/g, '\\t');
+}
+function resolveOutputDirectory(requestedOutDir, baseDir, silent) {
+    let validatedOutDir;
+    try {
+        validatedOutDir = SecurityUtils.validatePath(requestedOutDir, baseDir, {
+            allowAbsolute: true,
+        });
+    }
+    catch (error) {
+        if (!silent) {
+            console.error(SecurityUtils.sanitizeLogMessage(error.message));
+        }
+        process.exit(1);
+    }
+    if (fs.existsSync(validatedOutDir)) {
+        try {
+            const stats = fs.statSync(validatedOutDir);
+            if (!stats.isDirectory()) {
+                if (!silent) {
+                    console.error(`Invalid output path: ${SecurityUtils.sanitizeLogMessage(validatedOutDir)} must be a directory`);
+                }
+                process.exit(1);
+            }
+        }
+        catch (error) {
+            if (!silent) {
+                console.error(SecurityUtils.sanitizeLogMessage(error.message));
+            }
+            process.exit(1);
+        }
+    }
+    return validatedOutDir;
+}
+const TSX_CLI_PATH = getLocalTsxCliPath();
 const UMBRELLA_CONFIG_FILE = 'umbrella.config.json';
 const UMBRELLA_FILE_NAME = 'umbrella.ts';
 const PACKAGE_JSON_FILE = 'package.json';
@@ -64,6 +120,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:',
@@ -94,7 +151,7 @@ async function cmdInit(name, silent = false) {
     log(`Generated chart.ts file`, silent);
     log(`Run 'tl synth ${validName}' to generate complete Helm chart`, silent);
 }
-async function cmdSynth(chartDirOrOutDir, flags) {
+async function cmdSynth(chartDirOrOutDir, flags, explicitOutDir) {
     let chartDir = process.cwd();
     let outDir;
     if (chartDirOrOutDir && fs.existsSync(path.join(chartDirOrOutDir, 'chart.ts'))) {
@@ -103,27 +160,35 @@ async function cmdSynth(chartDirOrOutDir, flags) {
     else {
         outDir = chartDirOrOutDir;
     }
+    if (explicitOutDir) {
+        outDir = explicitOutDir;
+    }
     const chartFile = path.join(chartDir, 'chart.ts');
     const defaultOutDir = path.join(chartDir, 'dist');
     if (!fs.existsSync(chartFile)) {
         console.error('chart.ts not found. Run `tl init` first.');
         process.exit(1);
     }
-    const resolvedOutDir = outDir ? path.resolve(outDir) : defaultOutDir;
+    const requestedOutDir = outDir ?? defaultOutDir;
+    const validatedOutDir = resolveOutputDirectory(requestedOutDir, chartDir, flags?.silent);
     const originalContent = fs.readFileSync(chartFile, 'utf8');
-    const modifiedContent = originalContent.replace(/chart\.writeHelmChart\(['"][^'"]*['"]\)/, `chart.writeHelmChart('${resolvedOutDir}')`);
+    const safeOutDirLiteral = escapeForSingleQuotedLiteral(validatedOutDir);
+    let modifiedContent = originalContent.replace(/chart\.writeHelmChart\(['"][^'"]*['"]\)/, `chart.writeHelmChart('${safeOutDirLiteral}')`);
+    if (modifiedContent === originalContent) {
+        modifiedContent = originalContent.replace(/chart\.write\(['"][^'"]*['"]\)/, `chart.write('${safeOutDirLiteral}')`);
+    }
     const tempChartFile = path.join(chartDir, '.timonel-temp-chart.ts');
     fs.writeFileSync(tempChartFile, modifiedContent);
     const wrapperScript = `
 import { pathToFileURL } from 'url';
 
 // Import the modified chart file which should execute the synthesis directly
-await import(pathToFileURL('${tempChartFile}').href);
+await import(pathToFileURL(${JSON.stringify(tempChartFile)}).href);
 `;
     const wrapperFile = path.join(chartDir, '.timonel-wrapper.mjs');
     try {
         fs.writeFileSync(wrapperFile, wrapperScript);
-        const result = spawnSync('npx', ['tsx', wrapperFile].filter(Boolean), {
+        const result = spawnSync(process.execPath, [TSX_CLI_PATH, wrapperFile], {
             stdio: flags?.silent ? 'pipe' : 'inherit',
             encoding: 'utf8',
             cwd: chartDir,
@@ -234,18 +299,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}`);
@@ -304,28 +373,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);
@@ -390,30 +485,36 @@ async function cmdUmbrellaSynth(outDir, flags) {
         console.error('umbrella.ts not found. Run `tl umbrella init` first.');
         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, outDir ?? defaultOutDir, synthMode, flags);
 }
-async function executeTypeScriptUmbrella(resolvedPath, outDir, flags) {
+async function executeTypeScriptUmbrella(resolvedPath, outDir, mode, flags) {
+    const umbrellaBase = path.dirname(resolvedPath);
+    const validatedOutDir = resolveOutputDirectory(outDir, umbrellaBase, flags?.silent);
     const wrapperScript = `
 import { pathToFileURL } from 'url';
 
-const mod = await import(pathToFileURL('${resolvedPath}').href);
+const mod = await import(pathToFileURL(${JSON.stringify(resolvedPath)}).href);
 const runner = mod.default || mod.run || mod.synth;
 if (typeof runner !== 'function') {
   console.error('umbrella.ts must export a default/run/synth function');
   process.exit(1);
 }
 
-const output = '${outDir}';
+const output = ${JSON.stringify(validatedOutDir)};
+const synthOptions = { mode: ${JSON.stringify(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');
     try {
         fs.writeFileSync(wrapperFile, wrapperScript);
-        const result = spawnSync('npx', ['tsx', wrapperFile].filter(Boolean), {
+        const result = spawnSync(process.execPath, [TSX_CLI_PATH, wrapperFile], {
             stdio: flags?.silent ? 'pipe' : 'inherit',
             encoding: 'utf8',
         });
@@ -432,37 +533,81 @@ console.log('Umbrella chart written to ' + output);
 }
 function parseFlags(args) {
     const flags = {};
-    while (args.length > 0 && args[0]?.startsWith('-')) {
-        const flag = args.shift();
-        switch (flag) {
-            case '--dry-run':
+    const positionalArguments = [];
+    const takeValue = (flagName) => {
+        const value = args.shift();
+        if (value === undefined) {
+            usageAndExit(`Missing value for ${flagName}`, flags.silent);
+            return '';
+        }
+        return value;
+    };
+    const flagHandlers = new Map([
+        [
+            '--dry-run',
+            () => {
                 flags.dryRun = true;
-                break;
-            case '--silent':
+            },
+        ],
+        [
+            '--silent',
+            () => {
                 flags.silent = true;
-                break;
-            case '--env': {
-                const envValue = args.shift();
-                if (envValue)
+            },
+        ],
+        [
+            '--env',
+            () => {
+                const envValue = takeValue('--env');
+                if (envValue) {
                     flags.env = envValue;
-                break;
-            }
-            case '--set': {
-                const setValue = args.shift();
+                }
+            },
+        ],
+        [
+            '--set',
+            () => {
+                const setValue = takeValue('--set');
                 if (setValue) {
                     flags.set = flags.set || [];
                     flags.set.push(setValue);
                 }
-                break;
-            }
-            case '--help':
-            case '-h':
-                usageAndExit(undefined, flags.silent);
-                break;
-            default:
-                usageAndExit(`Unknown flag: ${flag}`, flags.silent);
+            },
+        ],
+        [
+            '--mode',
+            () => {
+                const modeValue = takeValue('--mode');
+                if (!UMBRELLA_SYNTH_MODES.includes(modeValue)) {
+                    usageAndExit('Invalid mode. Use "dependencies" or "inline".', flags.silent);
+                }
+                flags.mode = modeValue;
+            },
+        ],
+    ]);
+    const helpFlags = new Set(['--help', '-h']);
+    while (args.length > 0) {
+        const token = args.shift();
+        if (token === undefined) {
+            break;
+        }
+        if (!token.startsWith('-')) {
+            positionalArguments.push(token);
+            continue;
+        }
+        if (helpFlags.has(token)) {
+            usageAndExit(undefined, flags.silent);
+            return flags;
+        }
+        const handler = flagHandlers.get(token);
+        if (handler) {
+            handler();
+            continue;
         }
+        usageAndExit(`Unknown flag: ${token}`, flags.silent);
     }
+    args.length = 0;
+    args.push(...positionalArguments);
     return flags;
 }
 async function executeCommand(command, args, flags) {
@@ -471,7 +616,7 @@ async function executeCommand(command, args, flags) {
             await cmdInit(args[0], flags.silent);
             break;
         case 'synth':
-            await cmdSynth(args[0], flags);
+            await cmdSynth(args[0], flags, args[1]);
             break;
         case 'validate':
             await cmdValidate(flags);

package/dist/lib/helmChartWriter.d.ts

@@ -1,3 +1,5 @@
+import type { HelperDefinition as ExternalHelperDefinition } from './utils/helmHelpers/types.js';
+export type HelperDefinition = ExternalHelperDefinition;
 export interface HelmChartMeta {
     name: string;
     version: string;
@@ -43,10 +45,6 @@ export interface HelmChartWriteOptions {
     notesTpl?: string;
     valuesSchema?: Record<string, unknown>;
 }
-export interface HelperDefinition {
-    name: string;
-    body: string;
-}
 export declare class HelmChartWriter {
     static write(opts: HelmChartWriteOptions): void;
     private static createDirectories;

package/dist/lib/helmChartWriter.js

@@ -15,7 +15,9 @@ export class HelmChartWriter {
             assetCount: assets.length,
             operation: 'helm_write_start',
         });
-        const validatedOutDir = SecurityUtils.validatePath(outDir, process.cwd());
+        const validatedOutDir = SecurityUtils.validatePath(outDir, process.cwd(), {
+            allowAbsolute: true,
+        });
         this.createDirectories(validatedOutDir);
         this.writeChartYaml(validatedOutDir, meta);
         this.writeValuesFiles(validatedOutDir, defaultValues, envValues);
@@ -72,7 +74,7 @@ export class HelmChartWriter {
         }
         else if (Array.isArray(helpersTpl)) {
             content = helpersTpl
-                .map((h) => [`{{- define "${h.name}" -}}`, h.body.trimEnd(), '{{- end }}', ''].join('\n'))
+                .map((h) => [`{{- define "${h.name}" -}}`, h.template.trimEnd(), '{{- end }}', ''].join('\n'))
                 .join('\n');
         }
         fs.writeFileSync(path.join(outDir, 'templates', '_helpers.tpl'), content);
@@ -124,18 +126,14 @@ function splitDocs(yamlStr) {
 }
 function writeAssets(outDir, 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);
         try {
+            const { directorySegments, fileBaseName } = resolveAssetPath(asset.id);
             if (asset.singleFile) {
-                writeSingleAssetFile(outDir, targetDir, sanitizedId, asset.yaml);
+                writeSingleAssetFile(outDir, targetDir, directorySegments, fileBaseName, asset.yaml);
             }
             else {
-                writeMultipleAssetFiles(outDir, targetDir, sanitizedId, asset.yaml);
+                writeMultipleAssetFiles(outDir, targetDir, directorySegments, fileBaseName, asset.yaml);
             }
         }
         catch (error) {
@@ -147,16 +145,72 @@ function writeAssets(outDir, assets) {
 function getTargetDirectory(target) {
     return target === 'crds' ? 'crds' : 'templates';
 }
-function writeSingleAssetFile(outDir, targetDir, assetId, yaml) {
-    const filename = `${assetId}.yaml`;
-    fs.mkdirSync(path.join(outDir, targetDir), { recursive: true });
-    fs.writeFileSync(path.join(outDir, targetDir, filename), yaml + '\n');
+function writeSingleAssetFile(outDir, targetDir, directorySegments, fileBaseName, yaml) {
+    const chartSubdir = path.join(outDir, targetDir, ...directorySegments);
+    SecurityUtils.validatePath(chartSubdir, outDir);
+    fs.mkdirSync(chartSubdir, { recursive: true });
+    const filename = `${fileBaseName}.yaml`;
+    const absolutePath = path.join(chartSubdir, filename);
+    SecurityUtils.validatePath(absolutePath, outDir);
+    fs.writeFileSync(absolutePath, yaml.endsWith('\n') ? yaml : `${yaml}\n`);
 }
-function writeMultipleAssetFiles(outDir, targetDir, assetId, yaml) {
+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);
     parts.forEach((doc, index) => {
-        const filename = `${assetId}${parts.length > 1 ? `-${index + 1}` : ''}.yaml`;
-        fs.mkdirSync(path.join(outDir, targetDir), { recursive: true });
-        fs.writeFileSync(path.join(outDir, targetDir, filename), doc + '\n');
+        const suffix = parts.length > 1 ? `-${index + 1}` : '';
+        const filename = `${fileBaseName}${suffix}.yaml`;
+        const absolutePath = path.join(chartSubdir, filename);
+        SecurityUtils.validatePath(absolutePath, outDir);
+        fs.writeFileSync(absolutePath, doc.endsWith('\n') ? doc : `${doc}\n`);
+    });
+}
+function resolveAssetPath(assetId) {
+    if (!assetId || typeof assetId !== 'string') {
+        throw new Error('Asset ID must be a non-empty string');
+    }
+    if (assetId.includes('\0')) {
+        throw new Error('Asset ID cannot contain null bytes');
+    }
+    const normalized = assetId.replace(/\\+/g, '/');
+    const rawSegments = normalized.split('/');
+    if (rawSegments.length === 0) {
+        throw new Error('Asset ID must resolve to at least one segment');
+    }
+    const segments = rawSegments.map((segment) => {
+        if (!segment || segment.trim().length === 0) {
+            throw new Error('Asset path segments cannot be empty');
+        }
+        if (segment === '.' || segment === '..') {
+            throw new Error('Asset path segments cannot be relative references');
+        }
+        if (/[<>:"|?*]/.test(segment)) {
+            throw new Error('Asset path contains unsupported characters');
+        }
+        const hasControlCharacters = Array.from(segment).some((character) => {
+            const codePoint = character.codePointAt(0);
+            if (typeof codePoint !== 'number') {
+                return false;
+            }
+            if (codePoint < 0x20 || codePoint === 0x7f) {
+                return true;
+            }
+            if (codePoint >= 0x80 && codePoint <= 0x9f) {
+                return true;
+            }
+            return false;
+        });
+        if (hasControlCharacters) {
+            throw new Error('Asset path contains control characters');
+        }
+        return segment;
     });
+    const fileBaseName = segments[segments.length - 1];
+    const directorySegments = segments.slice(0, -1);
+    if (!fileBaseName) {
+        throw new Error('Asset ID must include a filename segment');
+    }
+    return { directorySegments, fileBaseName };
 }

package/dist/lib/security.d.ts

@@ -1,5 +1,8 @@
+export interface PathValidationOptions {
+    allowAbsolute?: boolean;
+}
 export declare class SecurityUtils {
-    static validatePath(inputPath: string, allowedBasePath: string): string;
+    static validatePath(inputPath: string, allowedBasePath: string, options?: PathValidationOptions): string;
     static sanitizeLogMessage(message: string): string;
     static sanitizeEnvironmentName(env: string): string;
     static isValidTypeScriptFile(filePath: string): boolean;

package/dist/lib/security.js

@@ -1,18 +1,68 @@
 import * as path from 'path';
 export class SecurityUtils {
-    static validatePath(inputPath, allowedBasePath) {
+    static validatePath(inputPath, allowedBasePath, options) {
         if (!inputPath || typeof inputPath !== 'string') {
             throw new Error('Invalid path: path must be a non-empty string');
         }
-        if (inputPath.includes('../') ||
-            inputPath.includes('..\\') ||
-            inputPath.includes('%2e%2e%2f') ||
-            inputPath.includes('%2e%2e%5c')) {
-            throw new Error('Invalid path: path traversal sequences detected');
+        if (inputPath.includes('\0')) {
+            throw new Error('Invalid path: null bytes are not permitted');
+        }
+        const allowAbsolute = Boolean(options?.allowAbsolute);
+        const candidates = new Set();
+        const registerCandidate = (value) => {
+            if (typeof value === 'string' && value.length > 0) {
+                candidates.add(value);
+            }
+        };
+        const addCandidate = (value) => {
+            if (typeof value !== 'string' || value.length === 0) {
+                return;
+            }
+            registerCandidate(value);
+            try {
+                const normalized = value.normalize('NFKC');
+                registerCandidate(normalized);
+            }
+            catch {
+            }
+        };
+        addCandidate(inputPath);
+        let decoded = inputPath;
+        for (let iteration = 0; iteration < 5; iteration += 1) {
+            try {
+                const nextDecoded = decodeURIComponent(decoded);
+                if (nextDecoded === decoded) {
+                    break;
+                }
+                decoded = nextDecoded;
+                addCandidate(decoded);
+            }
+            catch {
+                break;
+            }
+        }
+        const containsTraversalSequence = (candidate) => {
+            const lowered = candidate.toLowerCase();
+            if (lowered.includes('%2e%2f') || lowered.includes('%2e%5c') || lowered.includes('%2f%2e')) {
+                return true;
+            }
+            const normalized = candidate.replace(/\\+/g, '/');
+            const segments = normalized.split('/');
+            return segments.some((segment) => {
+                const loweredSegment = segment.toLowerCase();
+                return loweredSegment === '..' || loweredSegment === '%2e%2e';
+            });
+        };
+        for (const candidate of candidates) {
+            if (containsTraversalSequence(candidate)) {
+                throw new Error('Invalid path: path traversal sequences detected');
+            }
         }
         const resolvedInput = path.resolve(inputPath);
         const resolvedBase = path.resolve(allowedBasePath);
-        if (!resolvedInput.startsWith(resolvedBase + path.sep) && resolvedInput !== resolvedBase) {
+        const relativePath = path.relative(resolvedBase, resolvedInput);
+        const isInsideBase = relativePath === '' || (!relativePath.startsWith('..') && !path.isAbsolute(relativePath));
+        if (!(allowAbsolute && path.isAbsolute(inputPath)) && !isInsideBase) {
             throw new Error(`Invalid path: path must be within ${resolvedBase}`);
         }
         return resolvedInput;
@@ -41,7 +91,7 @@ export class SecurityUtils {
         return sanitized;
     }
     static isValidTypeScriptFile(filePath) {
-        const allowedExtensions = ['.ts', '.tsx'];
+        const allowedExtensions = ['.ts', '.tsx', '.cts', '.mts'];
         const ext = path.extname(filePath);
         return allowedExtensions.includes(ext);
     }

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/umbrellaRutter.js

@@ -16,7 +16,9 @@ export class UmbrellaRutter {
         }
     }
     write(outDir) {
-        const validatedOutDir = SecurityUtils.validatePath(outDir, process.cwd());
+        const validatedOutDir = SecurityUtils.validatePath(outDir, process.cwd(), {
+            allowAbsolute: true,
+        });
         mkdirSync(validatedOutDir, { recursive: true });
         mkdirSync(join(validatedOutDir, 'charts'), { recursive: true });
         for (const subchart of this.props.subcharts) {

package/dist/lib/utils/helmHelpers.d.ts

@@ -1,7 +1,5 @@
-export interface HelperDefinition {
-    name: string;
-    template: string;
-}
+import type { HelperDefinition } from './helmHelpers/types.js';
+export type { HelperDefinition } from './helmHelpers/types.js';
 export declare const STANDARD_HELPERS: HelperDefinition[];
 export declare const FILE_ACCESS_HELPERS: HelperDefinition[];
 export declare const TEMPLATE_FUNCTION_HELPERS: HelperDefinition[];

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "timonel",
   "type": "module",
-  "version": "2.12.0",
+  "version": "2.12.2-beta.1",
   "description": "Timonel: programmatic Helm chart generator using cdk8s (TypeScript)",
   "bin": {
     "timonel": "dist/cli.js",
@@ -92,7 +92,7 @@
     "constructs": "^10.4.2",
     "handlebars": "^4.7.8",
     "js-yaml": "^4.1.0",
-    "pino": "^9.11.0",
+    "pino": "^10.0.0",
     "pino-pretty": "^13.1.1",
     "ts-node": "^10.9.2",
     "yaml": "^2.8.1"