timonel 3.1.1 → 3.1.2

package/dist/cli.js

@@ -9,6 +9,11 @@ import { createLogger } from './lib/utils/logger.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const esmRequire = createRequire(import.meta.url);
+/**
+ * Resolves the project-local tsx CLI entry point for spawning through Node.js.
+ * @returns Absolute filesystem path to the tsx CLI module.
+ * @since 2.12.2 Prevents reliance on npx downloads during synthesis.
+ */
 function getLocalTsxCliPath() {
     try {
         return esmRequire.resolve('tsx/cli');
@@ -22,6 +27,12 @@ function getLocalTsxCliPath() {
         process.exit(1);
     }
 }
+/**
+ * Escapes a string for safe inclusion inside single-quoted TypeScript literals.
+ * @param value - Path or text segment that needs escaping.
+ * @returns Escaped string suitable for single-quoted literals.
+ * @since 2.12.2 Avoids malformed chart.ts rewrites when directories contain quotes.
+ */
 function escapeForSingleQuotedLiteral(value) {
     return value
         .replace(/\\/g, '\\\\')
@@ -30,6 +41,14 @@ function escapeForSingleQuotedLiteral(value) {
         .replace(/\n/g, '\\n')
         .replace(/\t/g, '\\t');
 }
+/**
+ * Resolves and validates an output directory against traversal and file misdirection attempts.
+ * @param requestedOutDir - Raw output directory provided via CLI arguments.
+ * @param baseDir - Directory that relative paths must remain within.
+ * @param silent - When true, suppresses console error output on failure.
+ * @returns Absolute, security-checked directory path.
+ * @since 2.12.2 Protects against traversal while permitting explicit absolute destinations.
+ */
 function resolveOutputDirectory(requestedOutDir, baseDir, silent) {
     let validatedOutDir;
     try {
@@ -43,8 +62,11 @@ function resolveOutputDirectory(requestedOutDir, baseDir, silent) {
         }
         process.exit(1);
     }
-    if (fs.existsSync(validatedOutDir)) {
+    if (
+    // eslint-disable-next-line security/detect-non-literal-fs-filename -- Path validated by SecurityUtils
+    fs.existsSync(validatedOutDir)) {
         try {
+            // eslint-disable-next-line security/detect-non-literal-fs-filename -- Path validated by SecurityUtils
             const stats = fs.statSync(validatedOutDir);
             if (!stats.isDirectory()) {
                 if (!silent) {
@@ -63,37 +85,65 @@ function resolveOutputDirectory(requestedOutDir, baseDir, silent) {
     return validatedOutDir;
 }
 const TSX_CLI_PATH = getLocalTsxCliPath();
+// Constants
 const UMBRELLA_CONFIG_FILE = 'umbrella.config.json';
 const UMBRELLA_FILE_NAME = 'umbrella.ts';
 const PACKAGE_JSON_FILE = 'package.json';
+// Helper functions
+/**
+ * Retrieves the version from the package manifest located next to the compiled CLI file
+ * @returns The version number or 'unknown' if not found
+ * @since 2.11.1 Uses the CLI directory as the base for manifest lookup in installed scenarios
+ */
 function getVersion() {
     try {
         const packagePath = path.resolve(__dirname, '..', PACKAGE_JSON_FILE);
         const allowedBase = path.resolve(__dirname, '..');
         const validatedPath = SecurityUtils.validatePath(packagePath, allowedBase);
+        // eslint-disable-next-line security/detect-non-literal-fs-filename -- Path validated by SecurityUtils
         const packageJson = JSON.parse(fs.readFileSync(validatedPath, 'utf8'));
         if (packageJson.version) {
             return packageJson.version;
         }
     }
     catch {
+        // Fallback handled below
     }
     if (process.env.npm_package_version) {
         return process.env.npm_package_version;
     }
     return 'unknown';
 }
+// Create CLI logger instance
 const cliLogger = createLogger('cli');
+/**
+ * Enhanced logging function that respects silent flag globally
+ * @param msg - Message to log
+ * @param silent - Whether to suppress output
+ * @since 2.10.3
+ */
 function log(msg, silent = false) {
     if (!silent) {
         cliLogger.info(msg, { operation: 'cli_log' });
     }
 }
+/**
+ * Enhanced error logging function that respects silent flag
+ * @param msg - Error message to log
+ * @param silent - Whether to suppress output
+ * @since 2.10.3
+ */
 function logError(msg, silent = false) {
     if (!silent) {
         cliLogger.error(msg, { operation: 'cli_error' });
     }
 }
+/**
+ * Display usage information and exit
+ * @param msg - Optional error message
+ * @param silent - Whether to suppress output
+ * @since 2.9.2
+ */
 function usageAndExit(msg, silent = false) {
     if (msg) {
         logError(`Error: ${msg}`, silent);
@@ -135,37 +185,68 @@ function usageAndExit(msg, silent = false) {
     }
     process.exit(msg ? 1 : 0);
 }
-async function cmdInit(name, silent = false) {
+/**
+ * Initialize a new chart
+ * @param name - The chart name to create
+ * @param silent - Whether to suppress output messages
+ * @param dryRun - When true, validate and report the operation without writing files
+ * @since 2.8.4 Updated to mention Helm chart generation instead of Kubernetes manifests
+ */
+async function cmdInit(name, silent = false, dryRun = false) {
     if (!name)
         usageAndExit('Missing <chart-name>');
-    const validName = name;
+    const validName = name; // Now guaranteed to be defined
+    // Validate chart name for security
     if (!SecurityUtils.isValidChartName(validName)) {
         usageAndExit('Invalid chart name. Must be lowercase, start with a letter, and contain only letters, numbers, and dashes.');
     }
     const cwd = process.cwd();
     const base = SecurityUtils.validatePath(path.join(cwd, validName), cwd);
     const chartFile = SecurityUtils.validatePath(path.join(base, 'chart.ts'), cwd);
+    if (dryRun) {
+        log(`Dry run: would create chart '${SecurityUtils.sanitizeLogMessage(validName)}' at ${SecurityUtils.sanitizeLogMessage(base)}`, silent);
+        return;
+    }
+    // Create directory
+    // eslint-disable-next-line security/detect-non-literal-fs-filename -- Path validated by SecurityUtils
     fs.mkdirSync(base, { recursive: true });
+    // Import template generator
     const { generateFlexibleSubchartTemplate } = await import('./lib/templates/flexible-subchart.js');
+    // Write chart file only - following CDK8s best practices
+    // eslint-disable-next-line security/detect-non-literal-fs-filename -- Path validated by SecurityUtils
     fs.writeFileSync(chartFile, generateFlexibleSubchartTemplate(validName));
     log(`Chart created at ${base}`, silent);
     log(`Generated chart.ts file`, silent);
     log(`Run 'tl synth ${validName}' to generate complete Helm chart`, silent);
 }
+/**
+ * Synthesizes a chart to generate a complete Helm chart structure.
+ * Creates Chart.yaml, values.yaml, templates/, and _helpers.tpl files.
+ * Supports both chart directory and output directory parameters.
+ *
+ * @param chartDirOrOutDir - Either the chart directory path or output directory path
+ * @param flags - CLI flags for controlling synthesis behavior
+ * @param explicitOutDir - Optional explicit destination directory for generated charts
+ * @since 2.8.4
+ * @since 2.12.2 Supports explicit output directory argument while retaining legacy behavior
+ */
 async function cmdSynth(chartDirOrOutDir, flags, explicitOutDir) {
     const cwd = process.cwd();
     let chartDir = cwd;
     let outDir;
+    // If the parameter is a directory containing chart.ts, use it as chart directory
     if (chartDirOrOutDir) {
         const resolvedPath = path.resolve(chartDirOrOutDir);
         const validatedPath = SecurityUtils.validatePath(resolvedPath, cwd, { allowAbsolute: true });
         const chartTsPath = SecurityUtils.validatePath(path.join(validatedPath, 'chart.ts'), cwd, {
             allowAbsolute: true,
         });
+        // eslint-disable-next-line security/detect-non-literal-fs-filename -- Path validated by SecurityUtils
         if (fs.existsSync(chartTsPath)) {
             chartDir = validatedPath;
         }
         else {
+            // Otherwise, treat it as output directory for backward compatibility
             outDir = chartDirOrOutDir;
         }
     }
@@ -178,20 +259,30 @@ async function cmdSynth(chartDirOrOutDir, flags, explicitOutDir) {
     const defaultOutDir = SecurityUtils.validatePath(path.join(chartDir, 'dist'), cwd, {
         allowAbsolute: true,
     });
+    // eslint-disable-next-line security/detect-non-literal-fs-filename -- Path validated by SecurityUtils
     if (!fs.existsSync(chartFile)) {
         console.error('chart.ts not found. Run `tl init` first.');
         process.exit(1);
     }
     const requestedOutDir = outDir ?? defaultOutDir;
     const validatedOutDir = resolveOutputDirectory(requestedOutDir, chartDir, flags?.silent);
+    if (flags?.dryRun) {
+        log(`Dry run: would synthesize ${SecurityUtils.sanitizeLogMessage(chartFile)} to ${SecurityUtils.sanitizeLogMessage(validatedOutDir)}`, flags.silent);
+        return;
+    }
+    // Read the original chart file and modify the writeHelmChart output directory
+    // eslint-disable-next-line security/detect-non-literal-fs-filename -- Path validated by SecurityUtils
     const originalContent = fs.readFileSync(chartFile, 'utf8');
     const safeOutDirLiteral = escapeForSingleQuotedLiteral(validatedOutDir);
     let modifiedContent = originalContent.replace(/chart\.writeHelmChart\(['"][^'"]*['"]\)/, `chart.writeHelmChart('${safeOutDirLiteral}')`);
     if (modifiedContent === originalContent) {
         modifiedContent = originalContent.replace(/chart\.write\(['"][^'"]*['"]\)/, `chart.write('${safeOutDirLiteral}')`);
     }
+    // Create a temporary modified chart file
     const tempChartFile = SecurityUtils.validatePath(path.join(chartDir, '.timonel-temp-chart.ts'), cwd, { allowAbsolute: true });
+    // eslint-disable-next-line security/detect-non-literal-fs-filename -- Path validated by SecurityUtils
     fs.writeFileSync(tempChartFile, modifiedContent);
+    // Create wrapper script for tsx execution
     const wrapperScript = `
 import { pathToFileURL } from 'url';
 
@@ -200,6 +291,7 @@ await import(pathToFileURL(${JSON.stringify(tempChartFile)}).href);
 `;
     const wrapperFile = path.join(chartDir, '.timonel-wrapper.mjs');
     try {
+        // eslint-disable-next-line security/detect-non-literal-fs-filename -- CLI tool needs dynamic paths
         fs.writeFileSync(wrapperFile, wrapperScript);
         const result = spawnSync(process.execPath, [TSX_CLI_PATH, wrapperFile], {
             stdio: flags?.silent ? 'pipe' : 'inherit',
@@ -214,14 +306,28 @@ await import(pathToFileURL(${JSON.stringify(tempChartFile)}).href);
         }
     }
     finally {
+        // Clean up wrapper file
+        // eslint-disable-next-line security/detect-non-literal-fs-filename -- CLI tool needs dynamic paths
         if (fs.existsSync(wrapperFile)) {
+            // eslint-disable-next-line security/detect-non-literal-fs-filename -- CLI tool needs dynamic paths
             fs.unlinkSync(wrapperFile);
         }
+        // Clean up temporary chart file
+        // eslint-disable-next-line security/detect-non-literal-fs-filename -- CLI tool needs dynamic paths
         if (fs.existsSync(tempChartFile)) {
+            // eslint-disable-next-line security/detect-non-literal-fs-filename -- CLI tool needs dynamic paths
             fs.unlinkSync(tempChartFile);
         }
     }
 }
+/**
+ * Validates a Helm chart using helm lint command.
+ * Runs helm lint on the current directory to check chart validity.
+ *
+ * @param flags - CLI flags for controlling validation behavior
+ * @since 2.8.4
+ * @since 2.11.1 Supports --env and --set flags for environment-specific linting
+ */
 async function cmdValidate(flags) {
     const lintArgs = ['lint', '.'];
     if (flags?.env) {
@@ -239,6 +345,10 @@ async function cmdValidate(flags) {
             lintArgs.push('--set', setValue);
         }
     }
+    if (flags?.dryRun) {
+        log('Dry run: would execute Helm lint for the current chart', flags.silent);
+        return;
+    }
     const result = spawnSync('helm', lintArgs, {
         stdio: flags?.silent ? 'pipe' : 'inherit',
         encoding: 'utf8',
@@ -250,20 +360,39 @@ async function cmdValidate(flags) {
         process.exit(result.status ?? 1);
     }
 }
+/**
+ * Validates Helm release name format to prevent command injection.
+ * @param release - The release name to validate
+ * @since 2.12.3
+ */
 function validateReleaseName(release) {
+    // Helm naming rules: lowercase alphanumeric with hyphens, max 53 chars
+    // eslint-disable-next-line security/detect-unsafe-regex -- Simple pattern, bounded length check
     if (!/^[a-z0-9]([-a-z0-9]*[a-z0-9])?$/.test(release) || release.length > 53) {
         console.error(`Invalid release name: ${SecurityUtils.sanitizeLogMessage(release)}`);
         console.error('Release name must be lowercase alphanumeric with hyphens (max 53 chars)');
         process.exit(1);
     }
 }
+/**
+ * Validates Kubernetes namespace format to prevent command injection.
+ * @param namespace - The namespace to validate
+ * @since 2.12.3
+ */
 function validateNamespace(namespace) {
+    // Kubernetes naming rules: lowercase alphanumeric with hyphens, max 63 chars
+    // eslint-disable-next-line security/detect-unsafe-regex -- Simple pattern, bounded length check
     if (!/^[a-z0-9]([-a-z0-9]*[a-z0-9])?$/.test(namespace) || namespace.length > 63) {
         console.error(`Invalid namespace: ${SecurityUtils.sanitizeLogMessage(namespace)}`);
         console.error('Namespace must be lowercase alphanumeric with hyphens (max 63 chars)');
         process.exit(1);
     }
 }
+/**
+ * Validates --set flag format to prevent command injection.
+ * @param setValue - The --set value to validate
+ * @since 2.12.3
+ */
 function validateSetFlag(setValue) {
     if (!/^[a-zA-Z0-9._[\]-]+=.+$/.test(setValue)) {
         console.error(`Invalid --set format: ${SecurityUtils.sanitizeLogMessage(setValue)}`);
@@ -271,9 +400,11 @@ function validateSetFlag(setValue) {
         process.exit(1);
     }
 }
-async function cmdDeploy(release, namespace, flags) {
-    if (!release)
-        usageAndExit('Missing <release>');
+/**
+ * Build validated Helm arguments for deployment.
+ * @returns Validated argument list for `helm upgrade --install`
+ */
+function buildDeployArgs(release, namespace, flags) {
     validateReleaseName(release);
     const args = ['upgrade', '--install', release, '.'];
     if (namespace) {
@@ -296,7 +427,30 @@ async function cmdDeploy(release, namespace, flags) {
             args.push('--set', setValue);
         }
     }
-    const result = spawnSync('helm', args.filter((arg) => Boolean(arg)), {
+    return args;
+}
+/**
+ * Deploys a Helm chart to a Kubernetes cluster.
+ * Uses helm upgrade --install to deploy or update a release.
+ *
+ * @param release - The release name for the deployment
+ * @param namespace - Optional namespace for the deployment
+ * @param flags - CLI flags for controlling deployment behavior
+ * @since 2.8.4
+ * @since 2.11.1 Honors --env and --set flags when invoking helm upgrade
+ */
+async function cmdDeploy(release, namespace, flags) {
+    if (!release)
+        usageAndExit('Missing <release>');
+    const args = buildDeployArgs(release, namespace, flags);
+    if (flags?.dryRun) {
+        const namespaceDescription = namespace
+            ? ` in namespace '${SecurityUtils.sanitizeLogMessage(namespace)}'`
+            : '';
+        log(`Dry run: would execute Helm upgrade --install for release '${SecurityUtils.sanitizeLogMessage(release)}'${namespaceDescription}`, flags.silent);
+        return;
+    }
+    const result = spawnSync('helm', args, {
         stdio: flags?.silent ? 'pipe' : 'inherit',
         encoding: 'utf8',
     });
@@ -307,6 +461,13 @@ async function cmdDeploy(release, namespace, flags) {
         process.exit(result.status ?? 1);
     }
 }
+/**
+ * Lists available chart templates.
+ * Shows all available templates that can be used with tl init.
+ *
+ * @param flags - CLI flags for controlling output format
+ * @since 2.8.4
+ */
 async function cmdTemplates(flags) {
     const templates = [
         {
@@ -326,6 +487,7 @@ async function cmdTemplates(flags) {
         },
     ];
     if (flags?.silent) {
+        // In silent mode, output only JSON for programmatic consumption
         console.log(JSON.stringify(templates, null, 2));
     }
     else {
@@ -337,6 +499,15 @@ async function cmdTemplates(flags) {
     }
 }
 const UMBRELLA_SYNTH_MODES = ['dependencies', 'inline'];
+/**
+ * Handles umbrella chart commands (init, add, synth).
+ * Routes to appropriate umbrella subcommand handlers.
+ *
+ * @param subcommand - The umbrella subcommand to execute
+ * @param args - Arguments for the subcommand
+ * @param flags - CLI flags for controlling behavior
+ * @since 2.8.4
+ */
 async function cmdUmbrella(subcommand, args, flags) {
     if (!subcommand)
         usageAndExit('Missing umbrella subcommand');
@@ -345,10 +516,10 @@ async function cmdUmbrella(subcommand, args, flags) {
     const mergedFlags = mergeCliFlags(flags, subcommandFlags);
     switch (subcommand) {
         case 'init':
-            await cmdUmbrellaInit(workingArgs[0], mergedFlags.silent);
+            await cmdUmbrellaInit(workingArgs[0], mergedFlags.silent, mergedFlags.dryRun);
             break;
         case 'add':
-            await cmdUmbrellaAdd(workingArgs[0], mergedFlags.silent);
+            await cmdUmbrellaAdd(workingArgs[0], mergedFlags.silent, mergedFlags.dryRun);
             break;
         case 'synth':
             await cmdUmbrellaSynth(workingArgs[0], mergedFlags);
@@ -357,44 +528,73 @@ async function cmdUmbrella(subcommand, args, flags) {
             usageAndExit(`Unknown umbrella subcommand: ${subcommand}`);
     }
 }
-async function cmdUmbrellaInit(name, silent = false) {
+/**
+ * Initializes a new umbrella chart.
+ * Creates an umbrella chart structure for managing multiple subcharts.
+ *
+ * @param name - The name of the umbrella chart
+ * @param silent - Whether to suppress output messages
+ * @param dryRun - When true, validate and report the operation without writing files
+ * @since 2.8.4
+ */
+async function cmdUmbrellaInit(name, silent = false, dryRun = false) {
     const MISSING_NAME_MSG = 'Missing umbrella chart name';
     if (!name)
         usageAndExit(MISSING_NAME_MSG);
-    const validName = name;
+    const validName = name; // Now guaranteed to be defined
     const base = path.join(process.cwd(), validName);
     const umbrellaFile = path.join(base, UMBRELLA_FILE_NAME);
     const configFile = path.join(base, UMBRELLA_CONFIG_FILE);
+    if (dryRun) {
+        log(`Dry run: would create umbrella chart '${SecurityUtils.sanitizeLogMessage(validName)}' at ${SecurityUtils.sanitizeLogMessage(base)}`, silent);
+        return;
+    }
+    // Create directory
+    // eslint-disable-next-line security/detect-non-literal-fs-filename -- CLI tool needs dynamic paths
     fs.mkdirSync(base, { recursive: true });
+    // Create umbrella.ts
+    // Import template generator
     const { generateUmbrellaChart } = await import('./lib/templates/umbrella-chart.js');
+    // Write umbrella.ts
+    // eslint-disable-next-line security/detect-non-literal-fs-filename -- CLI tool needs dynamic paths
     fs.writeFileSync(umbrellaFile, generateUmbrellaChart(validName));
+    // Create umbrella.config.json
     const config = {
         name: validName,
         version: getVersion(),
         description: `${validName} umbrella chart`,
         subcharts: [],
     };
+    // eslint-disable-next-line security/detect-non-literal-fs-filename -- CLI tool needs dynamic paths
     fs.writeFileSync(configFile, JSON.stringify(config, null, 2));
+    // Create charts directory for subcharts
     const chartsDir = path.join(base, 'charts');
+    // eslint-disable-next-line security/detect-non-literal-fs-filename -- CLI tool needs dynamic paths
     fs.mkdirSync(chartsDir, { recursive: true });
     log(`Umbrella chart structure created at ${base}`, silent);
     log(`Add subcharts with: tl umbrella add <subchart-name>`, silent);
 }
+/** Convert a kebab-case subchart name to the generated camelCase import identifier. */
 function toCamelCase(str) {
     return str.replace(/-([a-z])/g, (g) => g[1]?.toUpperCase() || '');
 }
+/** Find the final top-level import line in generated umbrella TypeScript source. */
 function findLastImportIndex(lines) {
     let lastImportIndex = -1;
     for (let i = 0; i < lines.length; i++) {
+        // eslint-disable-next-line security/detect-object-injection
         if (lines[i]?.trim().startsWith('import ')) {
             lastImportIndex = i;
+            // eslint-disable-next-line security/detect-object-injection
         }
         else if (lines[i]?.trim() && !lines[i]?.trim().startsWith('import ')) {
+            // Stop at first non-import, non-empty line
             break;
         }
     }
     return lastImportIndex;
 }
+/** Add an import statement to generated umbrella source without duplicating it. */
 function addImportStatement(content, importStatement) {
     if (content.includes(importStatement)) {
         return content;
@@ -409,6 +609,7 @@ function addImportStatement(content, importStatement) {
     }
     return lines.join('\n');
 }
+/** Rebuild the generated `SUBCHARTS` array body with a new unique entry. */
 function buildSubchartsContent(subchartsContent, subchartEntry) {
     const existingEntries = (subchartsContent || '')
         .split('\n')
@@ -425,6 +626,7 @@ function buildSubchartsContent(subchartsContent, subchartEntry) {
     }
     return `\n${lines.join('\n')}\n`;
 }
+/** Add a generated subchart factory entry to the umbrella source array. */
 function addSubchartToArray(content, chartName, camelCaseName) {
     const subchartsRegex = /(const SUBCHARTS[\s\S]*?=\s*\[)([\s\S]*?)(\];)/;
     const match = content.match(subchartsRegex);
@@ -439,6 +641,7 @@ function addSubchartToArray(content, chartName, camelCaseName) {
     const newBody = buildSubchartsContent(body, subchartEntry);
     return content.replace(subchartsRegex, `${prefix}${newBody}${suffix}`);
 }
+/** Merge CLI flags while preserving every repeated `--set` override. */
 function mergeCliFlags(base, override) {
     const merged = { ...(base || {}) };
     if (!override) {
@@ -459,66 +662,99 @@ function mergeCliFlags(base, override) {
     }
     return merged;
 }
+/** Persist a new subchart import and factory entry into `umbrella.ts`. */
 function updateUmbrellaTs(subchartPath, chartName) {
     const umbrellaFile = path.join(process.cwd(), UMBRELLA_FILE_NAME);
     const content = processUmbrellaFile(umbrellaFile, subchartPath, chartName);
     fs.writeFileSync(umbrellaFile, content);
 }
+/** Transform umbrella source text to reference a newly generated subchart. */
 function processUmbrellaFile(umbrellaFile, subchartPath, chartName) {
+    // eslint-disable-next-line security/detect-non-literal-fs-filename -- CLI tool needs dynamic paths
     let content = fs.readFileSync(umbrellaFile, 'utf8');
     const importData = createImportData(subchartPath, chartName);
     content = addImportStatement(content, importData.importStatement);
     content = addSubchartToArray(content, chartName, importData.camelCaseName);
     return content;
 }
+/** Build the import path, identifier, and statement for a generated subchart. */
 function createImportData(subchartPath, chartName) {
     const importPath = `./charts/${subchartPath}/chart`;
     const camelCaseName = toCamelCase(chartName);
     const importStatement = `import ${camelCaseName} from '${importPath}';`;
     return { importPath, camelCaseName, importStatement };
 }
-async function cmdUmbrellaAdd(subchartPath, silent = false) {
+/**
+ * Adds a subchart to an existing umbrella chart.
+ * Creates a new subchart and updates the umbrella configuration.
+ *
+ * @param subchartPath - The path/name for the new subchart
+ * @param silent - Whether to suppress output messages
+ * @param dryRun - When true, validate and report the operation without writing files
+ * @since 2.8.4
+ */
+async function cmdUmbrellaAdd(subchartPath, silent = false, dryRun = false) {
     const MISSING_SUBCHART_MSG = 'Missing subchart name or path';
     if (!subchartPath)
         usageAndExit(MISSING_SUBCHART_MSG);
-    const validSubchartPath = subchartPath;
+    const validSubchartPath = subchartPath; // Now guaranteed to be defined
     const configFile = path.join(process.cwd(), UMBRELLA_CONFIG_FILE);
     if (!fs.existsSync(configFile)) {
         console.error(`${UMBRELLA_CONFIG_FILE} not found. Run \`tl umbrella init\` first.`);
         process.exit(1);
     }
     const config = JSON.parse(fs.readFileSync(configFile, 'utf8'));
+    // Extract subchart name from path (last segment)
     const subchartName = path.basename(validSubchartPath);
+    // Create full subchart directory path
     const chartsRoot = path.join(process.cwd(), 'charts');
     const targetSubchartPath = path.join(chartsRoot, validSubchartPath);
     let subchartDir;
     try {
+        // @since 2.11.1 Ensure requested subchart path stays inside charts directory
         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('/');
+    if (dryRun) {
+        log(`Dry run: would add subchart '${SecurityUtils.sanitizeLogMessage(subchartName)}' at path '${SecurityUtils.sanitizeLogMessage(normalizedSubchartPath)}'`, silent);
+        return;
+    }
+    // eslint-disable-next-line security/detect-non-literal-fs-filename -- CLI tool needs dynamic paths
+    fs.mkdirSync(subchartDir, { recursive: true });
     const chartFile = SecurityUtils.validatePath(path.join(subchartDir, 'chart.ts'), chartsRoot);
     const { generateFlexibleSubchartTemplate } = await import('./lib/templates/flexible-subchart.js');
     const subchartContent = generateFlexibleSubchartTemplate(subchartName);
+    // eslint-disable-next-line security/detect-non-literal-fs-filename -- Path validated by SecurityUtils
     fs.writeFileSync(chartFile, subchartContent);
+    // Update config
     config.subcharts.push({
         name: subchartName,
         version: getVersion(),
         path: `./charts/${normalizedSubchartPath}/chart.ts`,
     });
     fs.writeFileSync(configFile, JSON.stringify(config, null, 2));
+    // Update umbrella.ts file automatically with the path
     updateUmbrellaTs(normalizedSubchartPath, subchartName);
     log(`Subchart ${subchartName} added to umbrella at path '${normalizedSubchartPath}'`, silent);
 }
+/**
+ * Synthesizes an umbrella chart to generate Helm charts for all subcharts.
+ * Executes the umbrella.ts file to generate charts for all configured subcharts.
+ *
+ * @param outDir - Optional output directory for generated charts
+ * @param flags - CLI flags for controlling synthesis behavior
+ * @since 2.8.4
+ */
 async function cmdUmbrellaSynth(outDir, flags) {
     const cwd = process.cwd();
     const umbrellaFile = SecurityUtils.validatePath(path.join(cwd, UMBRELLA_FILE_NAME), cwd);
     const defaultOutDir = SecurityUtils.validatePath(path.join(cwd, 'dist'), cwd);
+    // eslint-disable-next-line security/detect-non-literal-fs-filename -- Path validated by SecurityUtils
     if (!fs.existsSync(umbrellaFile)) {
         console.error('umbrella.ts not found. Run `tl umbrella init` first.');
         process.exit(1);
@@ -529,9 +765,14 @@ async function cmdUmbrellaSynth(outDir, flags) {
     }
     await executeTypeScriptUmbrella(umbrellaFile, outDir ?? defaultOutDir, synthMode, flags);
 }
+/** Execute an umbrella TypeScript entry point through the project-local tsx runtime. */
 async function executeTypeScriptUmbrella(resolvedPath, outDir, mode, flags) {
     const umbrellaBase = path.dirname(resolvedPath);
     const validatedOutDir = resolveOutputDirectory(outDir, umbrellaBase, flags?.silent);
+    if (flags?.dryRun) {
+        log(`Dry run: would synthesize umbrella chart ${SecurityUtils.sanitizeLogMessage(resolvedPath)} to ${SecurityUtils.sanitizeLogMessage(validatedOutDir)} in ${mode} mode`, flags.silent);
+        return;
+    }
     const wrapperScript = `
 import { pathToFileURL } from 'url';
 
@@ -552,6 +793,7 @@ console.log('Umbrella chart written to ' + output);
     const cwd = process.cwd();
     const wrapperFile = SecurityUtils.validatePath(path.join(cwd, '.timonel-umbrella-wrapper.mjs'), cwd);
     try {
+        // eslint-disable-next-line security/detect-non-literal-fs-filename -- Path validated by SecurityUtils
         fs.writeFileSync(wrapperFile, wrapperScript);
         const result = spawnSync(process.execPath, [TSX_CLI_PATH, wrapperFile], {
             stdio: flags?.silent ? 'pipe' : 'inherit',
@@ -565,11 +807,21 @@ console.log('Umbrella chart written to ' + output);
         }
     }
     finally {
+        // Cleanup wrapper file
+        // eslint-disable-next-line security/detect-non-literal-fs-filename -- Path validated by SecurityUtils
         if (fs.existsSync(wrapperFile)) {
+            // eslint-disable-next-line security/detect-non-literal-fs-filename -- Path validated by SecurityUtils
             fs.unlinkSync(wrapperFile);
         }
     }
 }
+// Main CLI function
+/**
+ * Parse command line flags with improved help handling
+ * @param args - Command line arguments
+ * @returns Parsed flags object
+ * @since 2.9.2
+ */
 function parseFlags(args) {
     const flags = {};
     const positionalArguments = [];
@@ -649,10 +901,11 @@ function parseFlags(args) {
     args.push(...positionalArguments);
     return flags;
 }
+/** Dispatch a parsed top-level CLI command to its implementation. */
 async function executeCommand(command, args, flags) {
     switch (command) {
         case 'init':
-            await cmdInit(args[0], flags.silent);
+            await cmdInit(args[0], flags.silent, flags.dryRun);
             break;
         case 'synth':
             await cmdSynth(args[0], flags, args[1]);
@@ -677,9 +930,15 @@ async function executeCommand(command, args, flags) {
             usageAndExit(`Unknown command: ${command}`, flags.silent);
     }
 }
+/**
+ * Enhanced main function with better error handling
+ * @since 2.9.2
+ */
 async function main() {
     const args = process.argv.slice(2);
+    // Check for silent flag early
     const isSilent = args.includes('--silent');
+    // Handle help flags first, before extracting command
     if (args.includes('--help') || args.includes('-h')) {
         usageAndExit(undefined, isSilent);
         return;
@@ -688,6 +947,7 @@ async function main() {
     const flags = parseFlags(args);
     await executeCommand(command, args, flags);
 }
+// Run CLI with enhanced error handling
 main().catch((error) => {
     const flags = parseFlags(process.argv.slice(2));
     if (!flags.silent) {