timonel 2.12.1 → 2.12.2-beta.1

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [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

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';
@@ -95,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'))) {
@@ -104,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,
@@ -421,26 +485,27 @@ 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;
     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);
+    await executeTypeScriptUmbrella(umbrellaFile, outDir ?? defaultOutDir, synthMode, 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 synthOptions = { mode: '${mode}' };
+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, synthOptions));
@@ -449,7 +514,7 @@ 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',
         });
@@ -468,45 +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 '--mode': {
-                const modeValue = args.shift();
-                if (!modeValue || !UMBRELLA_SYNTH_MODES.includes(modeValue)) {
+            },
+        ],
+        [
+            '--mode',
+            () => {
+                const modeValue = takeValue('--mode');
+                if (!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);
-                break;
-            default:
-                usageAndExit(`Unknown flag: ${flag}`, flags.silent);
+            },
+        ],
+    ]);
+    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) {
@@ -515,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/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.1",
+  "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"