@garyr/pt-cli 0.36.4 → 0.39.1

package/README.md

@@ -45,13 +45,15 @@ graph LR
 - Initialize new projects from learned templates
 - Define template variables for dynamic file customization
 - **Automatic Variable Detection:** Scans text files for `{{ var }}` syntax during `learn`/`update`
+- **Nested Variable Expansion (v0.36.0+):** Variables can contain other variable placeholders that are resolved iteratively
+- **Parent Directory `.env` File Scanning:** Automatically scans parent directories for `.env` files and uses their values as defaults
 - Auto-detect and suggest post-config setup tasks
 - Configure global post-config tasks in `~/.pt/config.yaml` (apply to all projects)
 - Baked-in defaults for common project types (javascript, python, godot, etc.)
 - Share templates or use as an API with JSON export/import
 - **Direct JSON scaffolding:** Initialize projects from a JSON file without registering in `config.yaml`
 - **Portable template configs:** `.pt-template.json` files make shared directories fully self-describing
-- Fully supports non-interactive mode (`--yes`, `--vars`) for AI agent automation
+- Fully supports non-interactive mode (`--yes`, `--vars`, `--name`, `--desc`) for AI agent automation
 
 ## Quick Start
 

package/dist/commands/addCommand.js

@@ -2,24 +2,114 @@ import fs from 'fs';
 import path from 'path';
 import chalk from 'chalk';
 import { loadConfig, saveConfig } from '../config.js';
+/**
+ * Validate JSON file exists and contains valid JSON
+ */
+function validateJsonFile(filePath) {
+    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;
+        return {
+            valid: false,
+            error: `JSON parse error: ${error.message}`
+        };
+    }
+}
+/**
+ * Validate template structure
+ */
+function validateTemplateStructure(data) {
+    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, jsonStr, options = {}) {
     const config = loadConfig();
+    // Determine if we're reading from file or string
+    const isFile = !!options.file;
+    let data;
     try {
-        let data;
-        if (options.file) {
+        if (isFile) {
+            // Validate file first
             const filePath = path.resolve(options.file);
-            data = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+            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;
+                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 = {};
-        // Basic validation: ensure we aren't accidentally adding a full config object
+        // Validate template structure
+        const structureValidation = validateTemplateStructure(data);
+        if (!structureValidation.valid) {
+            console.error(chalk.red(`Error: Invalid template structure - ${structureValidation.error}`));
+            process.exit(1);
+        }
+        // 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.'));
@@ -31,7 +121,7 @@ export function addCommand(name, jsonStr, options = {}) {
     }
     catch (e) {
         const error = e;
-        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/dist/commands/configCommand.js

@@ -9,15 +9,22 @@ export function configCommand(templateName, options = {}) {
                     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/dist/commands/initCommand.js

@@ -5,6 +5,61 @@ import { loadConfig, sanitizePath } from '../config.js';
 import chalk from 'chalk';
 import { processCopyFiles } from '../substitute.js';
 import { execSync } from 'child_process';
+/**
+ * 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) {
+    const envVars = {};
+    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, destPath, options = {}) {
     const config = loadConfig();
     let typeName = targetName;
@@ -86,6 +141,16 @@ export async function init(targetName, destPath, options = {}) {
     // Handle Variables
     let variables = {};
     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) => p.trim());

package/dist/commands/learnCommand.js

@@ -9,7 +9,16 @@ export async function learn(sourcePath, updateTemplate = null, options = {}) {
     // 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.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);
@@ -65,6 +74,8 @@ export async function learn(sourcePath, updateTemplate = null, options = {}) {
         }
     }
     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;
         }
@@ -92,6 +103,34 @@ export async function learn(sourcePath, updateTemplate = null, options = {}) {
                 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 = '';
     if (options.desc) {
@@ -124,6 +163,8 @@ export async function learn(sourcePath, updateTemplate = null, options = {}) {
         }
     }
     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)
@@ -146,6 +187,34 @@ export async function learn(sourcePath, updateTemplate = null, options = {}) {
             });
             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) => s.trim()).filter(Boolean) : [];
     const ignorePatterns = [...(config.ignore || []), ...cliIgnore];
@@ -466,7 +535,11 @@ export async function learn(sourcePath, updateTemplate = null, options = {}) {
             name: targetName,
             ...templateConfig
         };
-        console.log(JSON.stringify(output, null, 2));
+        // 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;
     }
     config.templates[targetName] = templateConfig;
@@ -508,10 +581,10 @@ function extractStructure(dirPath, rootPath, ignorePatterns) {
             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))
+            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 });
         }
     }

package/dist/config.js

@@ -84,12 +84,22 @@ export function loadConfig() {
     catch (err) {
         const error = err;
         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: []
+        };
     }
 }
 export function normalizeVariable(v) {

package/dist/index.js

@@ -32,15 +32,18 @@ program
     }
     catch (err) {
         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);
     }
 });
 program

package/dist/substitute.js

@@ -4,11 +4,32 @@ import path from 'path';
 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, variables) {
-    return content.replace(/\{\{\s*(\w+)\s*\}\}/g, (_, varName) => {
-        return variables[varName] ?? `{{${varName}}}`;
-    });
+export function substituteVariables(content, variables, maxIterations = 10) {
+    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;
 }
 /**
  * Processes copy_files tasks from a template.

package/doc/configuration.md

@@ -28,6 +28,63 @@ Instead of manual definition, `pt learn` and `pt update` automatically scan for
 
 These variables are then used during `copy_files` operations to replace `{{variable_name}}` placeholders in copied files.
 
+### Nested Variable Expansion (v0.36.0+)
+
+Starting with v0.36.0, `pt` supports **nested variable expansion** — variables can contain other variable placeholders that are resolved iteratively. This enables powerful configuration patterns like:
+
+```bash
+# In ~/.env or parent directory .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`
+
+This is particularly useful for:
+
+- **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}}`)
+
+### Parent Directory `.env` File Scanning
+
+`pt` automatically scans parent directories for `.env` files and uses their values as defaults during initialization. This enables:
+
+- **Project-wide defaults**: Store common values in a parent `.env` file
+- **Environment-specific configurations**: Use different `.env` files for dev/staging/prod
+- **Team collaboration**: Share common variable values across team projects
+
+**Example:**
+
+```bash
+# Project structure:
+my-project/
+├── .env          # Contains: prefix='rst_'
+├── sub-project/  # Initialize here
+│   └── ...
+```
+
+When you run `pt init my-template sub-project`, the `prefix` variable will be pre-filled with `rst_` from the parent `.env` file.
+
+**Behavior:**
+
+- Scans from the current directory up to 3 parent levels
+- Uses values from `.env` as defaults (still prompts if not in `.env`)
+- `--vars` CLI option overrides `.env` values
+- `.env` files are not committed to version control (use `.gitignore`)
+
 ## Post-Config Tasks
 
 Post-config tasks are optional commands that run after a project is initialized. They can be defined in a template or auto-detected from the source directory.
@@ -57,6 +114,7 @@ If the directory contains a `.pt-template.json` or `template.json` file with a `
 3. Alternatively, initialize a temporary project from your learned template (`pt init`), refine it manually, and then use `pt update` from that directory to "re-learn" the refined state.
 
 **Security Note:** All post-config commands are subject to security validation:
+
 - Dangerous commands (e.g., `curl`, `python`, `chmod`) trigger warnings with 5-second cancellation
 - Absolute blocks (e.g., `sudo`, `rm -rf`, `dd`) are never allowed
 - Rate limiting prevents runaway execution (50 commands per run)
@@ -125,7 +183,7 @@ Each task supports:
 
 ## Default Post-Config
 
-Default post-config tasks are defined at the top level of `~/.pt/config.yaml` under `default_post_config`. They serve as suggestions when creating or updating templates via `pt learn`. 
+Default post-config tasks are defined at the top level of `~/.pt/config.yaml` under `default_post_config`. They serve as suggestions when creating or updating templates via `pt learn`.
 
 Unlike previous versions, default tasks are **not** automatically applied during `pt init`. Instead, you select which ones to include when learning a template, and those selections are baked into the template's `post_config` list. This eliminates the need to repeat boilerplate setup (e.g. `git init`) across templates while keeping each template fully self-contained.
 
@@ -137,21 +195,21 @@ default_post_config:
     description: "Initialize git repository"
   - command: "git add -A && git commit -m 'Initial commit'"
     description: "Initial git commit"
-    checked: false  # default on, but user must manually check
+    checked: false # default on, but user must manually check
   - command: "git lfs install"
     description: "Install git-lfs hooks"
-    type: "godot"  # only applies to godot projects
+    type: "godot" # only applies to godot projects
 ```
 
 ### Fields
 
 Each default task supports the same fields as template post-config:
 
-| Field         | Description                                                                      |
-| ------------- | -------------------------------------------------------------------------------- |
-| `command`     | Shell command to run                                                             |
-| `description` | Shown to user during interactive selection                                       |
-| `checked`     | Default checkbox state (`true` by default); set `false` to require manual opt-in |
+| Field         | Description                                                                                        |
+| ------------- | -------------------------------------------------------------------------------------------------- |
+| `command`     | Shell command to run                                                                               |
+| `description` | Shown to user during interactive selection                                                         |
+| `checked`     | Default checkbox state (`true` by default); set `false` to require manual opt-in                   |
 | `type`        | Filter by project type (e.g. `"javascript"`); if set, task only applies when template type matches |
 
 ### Behavior
@@ -163,6 +221,7 @@ Each default task supports the same fields as template post-config:
 
 You can view current default tasks using `pt config` or `pt default-post-config`.
 To update default tasks programmatically or via CLI, use the `pt default-post-config` command:
+
 - `pt default-post-config`: List current default post-config tasks.
 - `pt default-post-config --set --json '...'`: Replace the default post-config tasks list via a JSON string or file.
 
@@ -247,6 +306,7 @@ Each entry supports:
 A plausible scenario for customizing a new project's `package.json` and `README.md`:
 
 **1. Define in `config.yaml`**:
+
 ```yaml
 templates:
   node_web_app:
@@ -265,6 +325,7 @@ templates:
 ```
 
 **2. Template source (`templates/package.json.tmpl`)**:
+
 ```json
 {
   "name": "{{project_name}}",
@@ -275,6 +336,7 @@ templates:
 
 **3. Resulting project file**:
 If the user enters `my-service` and `Jane Doe`, the file `package.json` will be created with:
+
 ```json
 {
   "name": "my-service",