@garyr/pt-cli 0.36.4 → 0.39.1

package/doc/usage.md

@@ -46,6 +46,77 @@ During `pt learn` or `pt update`, the tool automatically scans text files at the
 - **Global Suggestions:** Your global variables (defined in `~/.pt/config.yaml`) are automatically injected as additional suggestions during the learn process.
 - **Updating:** You can add new placeholders to a project folder and run `pt update <template_name>` to automatically register them in your existing template.
 
+### Using `.env` Files for Variable Defaults (v0.36.0+)
+
+Starting with v0.36.0, `pt` automatically scans parent directories for `.env` files and uses their values as defaults during initialization. This enables powerful configuration patterns:
+
+```bash
+# Create a .env file in your project directory
+echo "prefix='rst_'" > .env
+echo "project='MyProject'" >> .env
+
+# Initialize a project - variables are pre-filled from .env
+pt init my-template my-new-project
+```
+
+**Key Features:**
+
+- **Automatic Scanning:** Scans up to 3 parent directories for `.env` files
+- **Variable Pre-filling:** Values from `.env` are used as defaults in prompts
+- **Nested Variables:** Supports nested placeholders like `prefix='app_{{ env }}'`
+- **Override Support:** Use `--vars` to override `.env` values: `--vars project=OverriddenProject`
+
+**Example with Nested Variables:**
+
+```bash
+# .env file
+prefix='app_{{ env }}'
+env=prod
+project=MyApp
+
+# Template README.md.tmpl
+# Content: {{prefix}}_{{project}}
+
+# Result: app_prod_MyApp
+```
+
+**Security Note:** `.env` files are not committed to version control. Use `.gitignore` to exclude them:
+
+```bash
+# .gitignore
+.env
+*.env
+```
+
+### Nested Variable Expansion (v0.36.0+)
+
+The `pt` CLI now supports **nested variable expansion** — variables can contain other variable placeholders that are resolved iteratively. This enables powerful configuration patterns:
+
+```bash
+# In .env file:
+prefix='rst_{{ project }}'
+project=MyProject
+
+# During initialization, the system will:
+# 1. Load prefix='rst_{{ project }}' from .env
+# 2. Detect that prefix contains a {{ project }} placeholder
+# 3. Resolve {{ project }} to MyProject
+# 4. Set prefix to rst_MyProject
+```
+
+**Use Cases:**
+
+- **Project naming conventions:** `prefix='app_{{ env }}'` + `env=prod` → `app_prod`
+- **Path templates:** `template_path='docs/{{ project }}'` + `project=wiki` → `docs/wiki`
+- **Multi-level configurations:** Combine multiple `.env` files with nested references
+
+**How it works:**
+
+- Variables are expanded iteratively (up to 10 passes) to prevent infinite loops
+- Circular references are detected and stopped gracefully
+- Missing nested variables remain as `{{ variable }}` placeholders
+- Whitespace is preserved: `{{ unknown }}` stays as `{{ unknown }}` (not `{{unknown}}`)
+
 ## Initialize a project
 
 ```bash

package/doc/variable_substitution_example.md

@@ -76,3 +76,67 @@ The resulting `package.json` in `my-new-project/` will be:
   "license": "MIT"
 }
 ```
+
+## 4. Nested Variable Expansion (v0.36.0+)
+
+Starting with v0.36.0, you can use **nested variables** for more complex configurations. Create a `.env` file in your project directory or parent directory:
+
+```bash
+# .env file in parent directory
+prefix='rst_'
+project=MyProject
+```
+
+Then use these variables in your template files:
+
+**`templates/README.md.tmpl`**:
+```markdown
+# {{prefix}}{{project}}
+
+This is a nested variable example where:
+- prefix = 'rst_'
+- project = 'MyProject'
+- Result: 'rst_MyProject'
+```
+
+**Even more complex nesting:**
+```bash
+# .env file
+prefix='app_{{ env }}'
+env=prod
+project=MyApp
+version=2.0
+```
+
+Then in your template:
+```json
+{
+  "name": "{{prefix}}_{{project}}",
+  "version": "{{version}}"
+}
+```
+
+This will resolve to:
+```json
+{
+  "name": "app_prod_MyApp",
+  "version": "2.0"
+}
+```
+
+**How it works:**
+1. `pt` scans parent directories for `.env` files
+2. Loads variables from `.env` as defaults
+3. Expands nested placeholders iteratively (up to 10 passes)
+4. Resolves circular references gracefully
+
+**Example with nested placeholders:**
+```bash
+# .env file
+template_path='docs/{{ project }}'
+project=wiki
+```
+
+Result: `template_path` becomes `docs/wiki`
+
+**Important:** Missing nested variables remain as `{{ variable }}` placeholders (with preserved whitespace) to help identify configuration issues.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@garyr/pt-cli",
-  "version": "0.36.4",
+  "version": "0.39.1",
   "description": "Project Template CLI - Learn structures and initialize projects",
   "main": "dist/index.js",
   "bin": {

package/src/commands/addCommand.ts

@@ -7,23 +7,124 @@ export interface AddOptions {
   file?: string;
 }
 
+/**
+ * Validate JSON file exists and contains valid JSON
+ */
+function validateJsonFile(filePath: string): { valid: boolean; data?: any; error?: string } {
+  try {
+    // Check if file exists
+    if (!fs.existsSync(filePath)) {
+      return {
+        valid: false,
+        error: `File not found: ${filePath}`
+      };
+    }
+    
+    // Check file size (reasonable limit to prevent reading huge files)
+    const stats = fs.statSync(filePath);
+    if (stats.size > 10 * 1024 * 1024) { // 10MB limit
+      return {
+        valid: false,
+        error: `File too large (${stats.size} bytes). Maximum size is 10MB.`
+      };
+    }
+    
+    // Read and parse JSON
+    const content = fs.readFileSync(filePath, 'utf8');
+    if (!content.trim()) {
+      return {
+        valid: false,
+        error: 'File is empty'
+      };
+    }
+    
+    const data = JSON.parse(content);
+    return { valid: true, data };
+  } catch (e) {
+    const error = e as Error;
+    return {
+      valid: false,
+      error: `JSON parse error: ${error.message}`
+    };
+  }
+}
+
+/**
+ * Validate template structure
+ */
+function validateTemplateStructure(data: any): { valid: boolean; error?: string } {
+  if (!data || typeof data !== 'object') {
+    return {
+      valid: false,
+      error: 'Template data must be a JSON object'
+    };
+  }
+  
+  // Basic structure validation
+  if (data.description && typeof data.description !== 'string') {
+    return {
+      valid: false,
+      error: 'Template description must be a string'
+    };
+  }
+  
+  if (data.variables && Array.isArray(data.variables)) {
+    for (let i = 0; i < data.variables.length; i++) {
+      const v = data.variables[i];
+      if (!v.name || typeof v.name !== 'string') {
+        return {
+          valid: false,
+          error: `Variable at index ${i} must have a string 'name' field`
+        };
+      }
+    }
+  }
+  
+  return { valid: true };
+}
+
 export function addCommand(name: string, jsonStr: string | undefined, options: AddOptions = {}) {
   const config = loadConfig();
+  
+  // Determine if we're reading from file or string
+  const isFile = !!options.file;
+  let data: any;
+  
   try {
-    let data;
-    if (options.file) {
-      const filePath = path.resolve(options.file);
-      data = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    if (isFile) {
+      // Validate file first
+      const filePath = path.resolve(options.file!);
+      const validation = validateJsonFile(filePath);
+      
+      if (!validation.valid) {
+        console.error(chalk.red(`Error: ${validation.error}`));
+        console.error(chalk.gray(`File: ${filePath}`));
+        process.exit(1);
+      }
+      
+      data = validation.data;
     } else if (jsonStr) {
-      data = JSON.parse(jsonStr);
+      // Parse JSON string directly
+      try {
+        data = JSON.parse(jsonStr);
+      } catch (e) {
+        const error = e as Error;
+        console.error(chalk.red(`Error: Invalid JSON string - ${error.message}`));
+        process.exit(1);
+      }
     } else {
       console.error('Error: Either a JSON string or --file <path> must be provided.');
       process.exit(1);
     }
     
-    if (!config.templates) config.templates = {};
+    // Validate template structure
+    const structureValidation = validateTemplateStructure(data);
+    if (!structureValidation.valid) {
+      console.error(chalk.red(`Error: Invalid template structure - ${structureValidation.error}`));
+      process.exit(1);
+    }
     
-    // Basic validation: ensure we aren't accidentally adding a full config object
+    // Check for full config object
     if (data && data.templates && typeof data.templates === 'object') {
       console.error(chalk.red('Error: The provided JSON appears to be a full configuration file, not a single template.'));
       console.error(chalk.gray('If you want to import a specific template from it, extract that template object first.'));
@@ -35,7 +136,7 @@ export function addCommand(name: string, jsonStr: string | undefined, options: A
     console.log(chalk.green(`✓ Template "${name}" saved successfully.`));
   } catch (e) {
     const error = e as Error;
-    console.error(chalk.red(`Failed to parse template JSON: ${error.message}`));
+    console.error(chalk.red(`Failed to process template: ${error.message}`));
     process.exit(1);
   }
 }

package/src/commands/configCommand.ts

@@ -15,13 +15,20 @@ export function configCommand(templateName: string | undefined, options: ConfigO
           name: templateName,
           ...config.templates[templateName]
         };
-        console.log(JSON.stringify(output, null, 2));
+        // Safely drain stdout before allowing the process to close
+        process.stdout.write(JSON.stringify(output, null, 2) + '\n', () => {
+          process.exit(0);
+        });
       } else {
-        console.error(chalk.red(`Error: Template "${templateName}" not found.`));
-        process.exit(1);
+        process.stderr.write(chalk.red(`Error: Template "${templateName}" not found.\n`), () => {
+          process.exit(1);
+        });
       }
     } else {
-      console.log(JSON.stringify(config, null, 2));
+      // Safely drain the entire global config payload
+      process.stdout.write(JSON.stringify(config, null, 2) + '\n', () => {
+        process.exit(0);
+      });
     }
     return;
   }

package/src/commands/initCommand.ts

@@ -14,6 +14,71 @@ export interface InitOptions {
   file?: string;
 }
 
+/**
+ * Scan parent directories for .env files and parse their variables.
+ * Returns a map of variable names to their values, supporting:
+ * - KEY=VALUE format
+ * - KEY="VALUE with spaces" format
+ * - KEY='VALUE with spaces' format
+ * - Comments (lines starting with #)
+ * - Empty lines
+ */
+function scanEnvForVariables(targetPath: string): Record<string, string> {
+  const envVars: Record<string, string> = {};
+  let currentDir = path.resolve(targetPath);
+  
+  // Scan up to 5 parent directories for .env files
+  const maxDepth = 5;
+  
+  for (let depth = 0; depth < maxDepth; depth++) {
+    const envPath = path.join(currentDir, '.env');
+    
+    if (fs.existsSync(envPath)) {
+      try {
+        const content = fs.readFileSync(envPath, 'utf-8');
+        const lines = content.split('\n');
+        
+        for (const line of lines) {
+          const trimmed = line.trim();
+          
+          // Skip empty lines and comments
+          if (!trimmed || trimmed.startsWith('#')) {
+            continue;
+          }
+          
+          // Match KEY=VALUE patterns
+          const match = trimmed.match(/^([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.+)$/);
+          if (match) {
+            const key = match[1];
+            let value = match[2];
+            
+            // Remove surrounding quotes if present
+            if ((value.startsWith('"') && value.endsWith('"')) || 
+                (value.startsWith("'") && value.endsWith("'"))) {
+              value = value.slice(1, -1);
+            }
+            
+            envVars[key] = value;
+          }
+        }
+      } catch (err) {
+        // Silently skip unreadable .env files
+        continue;
+      }
+    }
+    
+    // Move to parent directory
+    const parentDir = path.dirname(currentDir);
+    if (parentDir === currentDir) {
+      // Reached filesystem root
+      break;
+    }
+    currentDir = parentDir;
+  }
+  
+  return envVars;
+}
+
 export async function init(targetName: string | undefined, destPath: string | undefined, options: InitOptions = {}) {
   const config = loadConfig();
 
@@ -103,6 +168,18 @@ export async function init(targetName: string | undefined, destPath: string | un
   // Handle Variables
   let variables: Record<string, string> = {};
   if (template.variables && template.variables.length > 0) {
+    // Scan parent directories for .env files and pre-fill variables
+    const envVars = scanEnvForVariables(resolvedDest);
+    
+    // Merge .env variables into variables (with lower priority than --vars)
+    if (Object.keys(envVars).length > 0) {
+      for (const [key, value] of Object.entries(envVars)) {
+        if (!variables[key]) {
+          variables[key] = value;
+        }
+      }
+    }
+    
     if (options.vars) {
       // Parse --vars "key=val,key2=val2"
       const pairs = options.vars.split(',').map((p: string) => p.trim());

package/src/commands/learnCommand.ts

@@ -21,7 +21,15 @@ export async function learn(sourcePath: string, updateTemplate: string | null =
   // Phase 1: Remote Check
   if (sourcePath.startsWith('http')) {
     console.log(chalk.cyan(`Downloading remote template from: ${sourcePath}...`));
-    resolvedPath = await downloadAndExtract(sourcePath, options.json || false, options.allowUntrusted || false);
+    try {
+      resolvedPath = await downloadAndExtract(sourcePath, options.json || false, options.allowUntrusted || false);
+    } catch (err) {
+      if ((err as Error).message === 'Download cancelled by user due to untrusted source') {
+        console.log(chalk.yellow('Download cancelled. Exiting.'));
+        process.exit(0);
+      }
+      throw err;
+    }
   } else {
     resolvedPath = path.resolve(sourcePath);
   }
@@ -78,6 +86,9 @@ export async function learn(sourcePath: string, updateTemplate: string | null =
       process.exit(1);
     }
   } else {
+    // Track whether name came from .info.md or JSON (not user-provided)
+    const nameFromSource = !options.name && (fileTemplateConfig.name || infoName);
+    
     if (options.name) {
       targetName = options.name;
     } else if (fileTemplateConfig.name) {
@@ -99,6 +110,34 @@ export async function learn(sourcePath: string, updateTemplate: string | null =
         targetName = newName;
       }
     }
+    
+    // If name came from .info.md or JSON, prompt to confirm/edit
+    // This prevents accidental overwrites when creating new templates based on existing ones
+    if (nameFromSource && !options.json) {
+      if (options.yes) {
+        // In --yes mode, keep the auto-detected name but warn
+        const existingNames = getTemplateNames(config);
+        if (existingNames.includes(targetName)) {
+          console.warn(chalk.yellow(`⚠ Warning: "${targetName}" already exists. Using this name will overwrite the existing template.`));
+        }
+      } else {
+        const { confirmName } = await inquirer.prompt({
+          type: 'confirm',
+          name: 'confirmName',
+          message: `Use "${targetName}" as the template name?`,
+          default: true
+        });
+        if (!confirmName) {
+          const { newName } = await inquirer.prompt({
+            type: 'input',
+            name: 'newName',
+            message: 'Name this template:',
+            default: targetName
+          });
+          targetName = newName;
+        }
+      }
+    }
   }
 
   let description = '';
@@ -129,6 +168,9 @@ export async function learn(sourcePath: string, updateTemplate: string | null =
       }
     }
   } else {
+    // Track whether description came from .info.md or JSON (not user-provided)
+    const descFromSource = !options.desc && (fileTemplateConfig.description || infoDesc);
+    
     if (fileTemplateConfig.description) {
       description = fileTemplateConfig.description;
       if (!options.json) console.log(chalk.cyan(`Auto-detected template description from JSON: ${description}`));
@@ -146,6 +188,34 @@ export async function learn(sourcePath: string, updateTemplate: string | null =
       });
       description = newDesc;
     }
+    
+    // If description came from .info.md or JSON, prompt to confirm/edit
+    // This prevents accidental overwrites when creating new templates based on existing ones
+    if (descFromSource && !options.json) {
+      if (options.yes) {
+        // In --yes mode, keep the auto-detected description but warn
+        const existingNames = getTemplateNames(config);
+        if (existingNames.includes(targetName)) {
+          console.warn(chalk.yellow(`⚠ Warning: "${targetName}" already exists. Using this name will overwrite the existing template.`));
+        }
+      } else {
+        const { confirmDesc } = await inquirer.prompt({
+          type: 'confirm',
+          name: 'confirmDesc',
+          message: `Use "${description}" as the template description?`,
+          default: true
+        });
+        if (!confirmDesc) {
+          const { newDesc } = await inquirer.prompt({
+            type: 'input',
+            name: 'newDesc',
+            message: 'Purpose/Description of this template:',
+            default: description
+          });
+          description = newDesc;
+        }
+      }
+    }
   }
 
   const cliIgnore = options.ignore ? options.ignore.split(',').map((s: string) => s.trim()).filter(Boolean) : [];
@@ -472,11 +542,16 @@ export async function learn(sourcePath: string, updateTemplate: string | null =
   }
 
   if (options.json) {
-    const output = {
-      name: targetName,
-      ...templateConfig
-    };
-    console.log(JSON.stringify(output, null, 2));
+  const output = {
+    name: targetName,
+    ...templateConfig
+  };
+  
+    // Force the application to wait until every single byte of this JSON string 
+    // safely clears the operating system's pipe buffer before letting the process die.
+    process.stdout.write(JSON.stringify(output, null, 2) + '\n', () => {
+      process.exit(0);
+    });
     return;
   }
 
@@ -518,8 +593,8 @@ function extractStructure(dirPath: string, rootPath: string, ignorePatterns?: st
       let info = "";
       const gitkeepPath = path.join(fullPath, '.gitkeep.md');
       const infoPath = path.join(fullPath, '.info.md');
-      if (fs.existsSync(gitkeepPath)) info = fs.readFileSync(gitkeepPath, 'utf-8').trim();
-      else if (fs.existsSync(infoPath)) info = fs.readFileSync(infoPath, 'utf-8').trim();
+      if (fs.existsSync(infoPath)) info = fs.readFileSync(infoPath, 'utf-8').trim();
+      else if (fs.existsSync(gitkeepPath)) info = fs.readFileSync(gitkeepPath, 'utf-8').trim();
       nodes.push({ name: entry.name, info: info, children: children });
     }
   } catch (e) {}

package/src/config.ts

@@ -148,12 +148,24 @@ export function loadConfig(): PtConfig {
   } catch (err) {
     const error = err as Error;
     console.error(chalk.red(`\nError loading config: ${error.message}`));
-    // If we have a backup, maybe suggest using it
     const backupPath = getConfigPath() + '.bak';
     if (fs.existsSync(backupPath)) {
       console.error(chalk.yellow(`A backup exists at ${backupPath}. You may want to restore it.`));
     }
-    process.exit(1);
+    
+    // Allow the event loop to flush console streams out to Godot before dying
+    setTimeout(() => {
+      process.exit(1);
+    }, 5);
+
+    // 👇 Add this return statement to satisfy the TypeScript compiler
+    // The application will terminate before this empty config can be used.
+    return {
+      version: '3.0',
+      templates: {},
+      default_post_config: [],
+      variables: []
+    };
   }
 }
 

package/src/index.ts

@@ -39,14 +39,17 @@ program
       await learn(pathArg || '.', null, options);
     } catch (err: any) {
       if (options.json) {
-        console.log(JSON.stringify({
+        // Fix: Ensure the error JSON payload isn't truncated before exiting
+        process.stdout.write(JSON.stringify({
           type: 'error',
           message: err.message || String(err)
-        }));
+        }) + '\n', () => {
+          process.exit(1);
+        });
       } else {
         console.error(chalk.red(`Error: ${err.message || err}`));
+        process.exit(1);
       }
-      process.exit(1);
     }
   });
 

package/src/substitute.ts

@@ -7,14 +7,39 @@ import { sanitizePath } from './config.js';
 
 /**
  * Replaces all {{var}} patterns in the content with values from the variables object.
+ * Supports nested variable expansion - if a variable's value contains {{other_var}},
+ * it will be expanded iteratively until no more placeholders remain or maxIterations is reached.
  */
 export function substituteVariables(
   content: string,
-  variables: Record<string, string>
+  variables: Record<string, string>,
+  maxIterations: number = 10
 ): string {
-  return content.replace(/\{\{\s*(\w+)\s*\}\}/g, (_, varName) => {
-    return variables[varName] ?? `{{${varName}}}`;
-  });
+  let result = content;
+  let iteration = 0;
+  
+  // Keep expanding until no more placeholders remain or we hit the limit
+  while (/\{\{[^}]+\}\}/.test(result) && iteration < maxIterations) {
+    // Use a more complex regex that captures the full placeholder including spaces
+    result = result.replace(/(\{\{\s*)(\w+)(\s*\}\})/g, (_, prefix, varName, suffix) => {
+      const val = variables[varName];
+      // If variable not found, leave placeholder as-is with original spacing
+      if (val === undefined) {
+        return `${prefix}${varName}${suffix}`;
+      }
+      // Return the value (which may contain more placeholders to expand)
+      return val;
+    });
+    iteration++;
+    
+    // Prevent infinite loops by checking if we're stuck
+    if (iteration > 1 && result === content) {
+      console.warn(chalk.yellow(`Warning: Potential infinite loop detected in variable expansion, stopping after ${iteration} iterations`));
+      break;
+    }
+  }
+  
+  return result;
 }
 
 /**