@garyr/pt-cli 0.38.0 → 0.40.0

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

@@ -3,6 +3,7 @@ import { Command } from 'commander';
 import chalk from 'chalk';
 // Command imports
 import { learn } from './commands/learnCommand.js';
+import { update } from './commands/updateCommand.js';
 import { init } from './commands/initCommand.js';
 import { configCommand } from './commands/configCommand.js';
 import { ignoreCommand } from './commands/ignoreCommand.js';
@@ -32,15 +33,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
@@ -49,9 +53,10 @@ program
     .option('--ignore <patterns>', 'Folder patterns to ignore (comma-separated)')
     .option('-y, --yes', 'Automatically confirm prompts')
     .option('--desc <description>', 'Template description (skip prompt)')
+    .option('--no-diff', 'Disable additive mode, show full list')
     .action(async (templateName, sourcePath, options) => {
     try {
-        await learn(sourcePath || '.', templateName, options);
+        await update(sourcePath || '.', templateName, options);
     }
     catch (err) {
         console.error(chalk.red(`Error: ${err.message || err}`));

package/doc/configuration.md

@@ -39,17 +39,20 @@ 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
@@ -64,6 +67,7 @@ This is particularly useful for:
 - **Team collaboration**: Share common variable values across team projects
 
 **Example:**
+
 ```bash
 # Project structure:
 my-project/
@@ -75,6 +79,7 @@ my-project/
 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
@@ -109,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)
@@ -177,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.
 
@@ -189,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
@@ -215,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.
 
@@ -299,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:
@@ -317,6 +325,7 @@ templates:
 ```
 
 **2. Template source (`templates/package.json.tmpl`)**:
+
 ```json
 {
   "name": "{{project_name}}",
@@ -327,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",

package/doc/usage.md

@@ -7,9 +7,13 @@
 pt learn /path/to/PROJECT
 
 # Update an existing template (use current directory if no path given)
+# (Runs in additive difference mode by default: shows only new items, auto-selected, for de-selection)
 pt update <template_name>
 pt update <template_name> /path/to/PROJECT
 
+# Use full mode (original behavior, presents all items)
+pt update <template_name> /path/to/PROJECT --no-diff
+
 # Ignore specific folders during learning
 pt learn /path/to/PROJECT --ignore=DAILIES/*,PARKING_LOT/*,REFERENCE/*
 
@@ -60,12 +64,14 @@ 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 }}'
@@ -79,6 +85,7 @@ project=MyApp
 ```
 
 **Security Note:** `.env` files are not committed to version control. Use `.gitignore` to exclude them:
+
 ```bash
 # .gitignore
 .env
@@ -102,11 +109,13 @@ project=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

package/package.json

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

package/skills/agency-pt-operator/SKILL.md

@@ -27,7 +27,11 @@ As an agent equipped with this skill, you have the ability to rapidly scaffold,
 3. **Capturing Knowledge (`pt learn`):**
    If you spend time establishing a new, complex directory structure or configuration (e.g., a specific flavor of an Express backend with testing hooks), save it! Remote URLs (GitHub, Gitea, etc.) are automatically translated to tarball downloads.
    - **Command:** `pt learn <source_path> --name <template_name> --desc "<Description>" --yes`
-   - **Update existing template:** Update an existing template with new structure/files: `pt update <template_name> <source_path> --yes`
+   - **Update existing template:** Update an existing template with new structure/files: `pt update <template_name> <source_path> --yes`.
+     - **Additive Difference Mode (Default):** By default, `pt update` operates in an additive mode that only presents *new* folders, files, and variables from the target directory to the user for de-selection. Existing items and their configurations (such as `substitute_variables` and `post_copy` settings) are preserved as-is.
+     - **Editing Metadata:** During update, description and templateRoot are presented for editing with the existing template values pre-filled as defaults.
+     - **Global/Default Variables:** Default/global variables require the user to explicitly opt-in via checkboxes, rather than being automatically added.
+     - **Full/Original Mode:** To review all items manually instead of showing differences only, pass the `--no-diff` flag: `pt update <template_name> <source_path> --no-diff`
    - **Remote Templates:** Learn from a remote Git repository or archive URL directly! Pass the HTTP/HTTPS URL as the `<source_path>`:
      `pt learn https://github.com/username/my-template --name my_template --desc "Description" --yes`
    - Explain to the user that you've captured this template for future use.
@@ -191,7 +195,7 @@ For more details, see the [Security Guide](security.md).
 | Command | Description |
 |---------|-------------|
 | `pt learn <path>` | Learn a project structure from an existing directory |
-| `pt update <template> [path]` | Update an existing template with new structure/files |
+| `pt update <template> [path]` | Update an existing template (additive difference mode by default, use --no-diff for full mode) |
 | `pt init [template] [dest]` | Initialize a new project from a learned template |
 | `pt config [template]` | Show current config location and list templates, or export a specific template |
 | `pt variables [pairs]` | View or set global variables (comma-separated key=value) |

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/learnCommand.ts

@@ -542,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;
   }
 
@@ -588,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) {}