@garyr/pt-cli 0.27.0 → 0.28.0

package/README.md

@@ -41,6 +41,7 @@ graph LR
 ## Features at a Glance
 
 - Learn any directory structure and save it as a reusable template
+- **Remote Templates:** Learn templates directly from a remote repository or archive URL (GitHub, Gitea, etc.)
 - 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`
@@ -48,6 +49,8 @@ graph LR
 - 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
 
 ## Quick Start
@@ -67,9 +70,12 @@ npm link
 ### Basic Commands
 
 ```bash
-# Learn an existing project structure
+# Learn an existing local project structure
 pt learn /path/to/PROJECT
 
+# Learn a template from a remote repository (GitHub, Gitea, or tarball URL)
+pt learn https://github.com/garyritchie/pt_godot
+
 # Scaffold a new project from a template
 pt init <template_name> /path/to/NEW_PROJECT
 
@@ -81,6 +87,9 @@ pt config my-template --json > my-template.json
 
 # Import a template from JSON
 pt add my-new-template --file my-new-template.json
+
+# Scaffold directly from a JSON file (no config registration)
+pt init ./new-project --file my-template.json --yes
 ```
 
 ## Documentation

package/dist/commands/initCommand.js

@@ -8,37 +8,58 @@ import { execSync } from 'child_process';
 export async function init(targetName, destPath, options = {}) {
     const config = loadConfig();
     let typeName = targetName;
-    // If no name provided, list templates
-    if (!typeName) {
-        const names = Object.keys(config.templates);
-        if (names.length === 0) {
-            console.log(chalk.red("No templates found. Run 'pt learn <path>' first."));
-            return;
+    let dest = destPath;
+    let template;
+    if (options.file) {
+        // If direct template file is specified, targetName could be the destPath if destPath is omitted
+        if (typeName && !dest) {
+            dest = typeName;
+            typeName = undefined;
         }
-        if (options.yes) {
-            console.error(chalk.red("No project type specified and running in non-interactive mode."));
+        try {
+            const fileContent = fs.readFileSync(options.file, 'utf-8');
+            template = JSON.parse(fileContent);
+        }
+        catch (e) {
+            console.error(chalk.red(`Error: Failed to read/parse template file "${options.file}": ${e.message}`));
             process.exit(1);
         }
-        const { selected } = await inquirer.prompt({
-            type: 'list',
-            name: 'selected',
-            message: 'Select Project Type:',
-            loop: false,
-            theme: {
-                icon: {
-                    cursor: chalk.green('[x] ')
-                }
-            },
-            choices: names.map(n => ({ name: n, value: n }))
-        });
-        typeName = selected;
+        if (!typeName) {
+            typeName = template.name || 'custom-template';
+        }
     }
-    const template = config.templates[typeName];
-    if (!template) {
-        console.error(chalk.red(`Template "${typeName}" not found.`));
-        process.exit(1);
+    else {
+        // If no name provided, list templates
+        if (!typeName) {
+            const names = Object.keys(config.templates);
+            if (names.length === 0) {
+                console.log(chalk.red("No templates found. Run 'pt learn <path>' first."));
+                return;
+            }
+            if (options.yes) {
+                console.error(chalk.red("No project type specified and running in non-interactive mode."));
+                process.exit(1);
+            }
+            const { selected } = await inquirer.prompt({
+                type: 'list',
+                name: 'selected',
+                message: 'Select Project Type:',
+                loop: false,
+                theme: {
+                    icon: {
+                        cursor: chalk.green('[x] ')
+                    }
+                },
+                choices: names.map(n => ({ name: n, value: n }))
+            });
+            typeName = selected;
+        }
+        template = config.templates[typeName];
+        if (!template) {
+            console.error(chalk.red(`Template "${typeName}" not found.`));
+            process.exit(1);
+        }
     }
-    let dest = destPath;
     if (!dest) {
         if (options.yes) {
             console.error(chalk.red("No destination path specified and running in non-interactive mode."));

package/dist/commands/learnCommand.js

@@ -21,6 +21,26 @@ export async function learn(sourcePath, updateTemplate = null, options = {}) {
     const isUpdate = !!updateTemplate;
     const config = loadConfig();
     const existingNames = getTemplateNames(config);
+    // Check for template configuration JSON file (.pt-template.json or template.json)
+    let fileTemplateConfig = {};
+    const jsonConfigPaths = [
+        path.join(resolvedPath, '.pt-template.json'),
+        path.join(resolvedPath, 'template.json')
+    ];
+    for (const jPath of jsonConfigPaths) {
+        if (fs.existsSync(jPath)) {
+            try {
+                const fileContent = fs.readFileSync(jPath, 'utf-8');
+                fileTemplateConfig = JSON.parse(fileContent);
+                if (!options.json)
+                    console.log(chalk.cyan(`Auto-detected template configurations from ${path.basename(jPath)}`));
+                break;
+            }
+            catch (e) {
+                console.warn(chalk.yellow(`Warning: Failed to parse ${path.basename(jPath)}: ${e.message}`));
+            }
+        }
+    }
     // Check for .info.md
     let infoName = '';
     let infoDesc = '';
@@ -48,6 +68,11 @@ export async function learn(sourcePath, updateTemplate = null, options = {}) {
         if (options.name) {
             targetName = options.name;
         }
+        else if (fileTemplateConfig.name) {
+            targetName = fileTemplateConfig.name;
+            if (!options.json)
+                console.log(chalk.cyan(`Auto-detected template name from JSON: ${targetName}`));
+        }
         else if (infoName) {
             targetName = infoName;
             if (!options.json)
@@ -99,7 +124,12 @@ export async function learn(sourcePath, updateTemplate = null, options = {}) {
         }
     }
     else {
-        if (infoDesc) {
+        if (fileTemplateConfig.description) {
+            description = fileTemplateConfig.description;
+            if (!options.json)
+                console.log(chalk.cyan(`Auto-detected template description from JSON: ${description}`));
+        }
+        else if (infoDesc) {
             description = infoDesc;
             if (!options.json)
                 console.log(chalk.cyan(`Auto-detected template description from .info.md: ${description}`));
@@ -129,6 +159,9 @@ export async function learn(sourcePath, updateTemplate = null, options = {}) {
     if (isUpdate && config.templates[updateTemplate].variables) {
         variables = [...config.templates[updateTemplate].variables];
     }
+    else if (fileTemplateConfig.variables && Array.isArray(fileTemplateConfig.variables)) {
+        variables = [...fileTemplateConfig.variables];
+    }
     // Add detected variables if not already present
     for (const varName of detectedVars) {
         if (!variables.some(v => v.name === varName)) {
@@ -180,7 +213,9 @@ export async function learn(sourcePath, updateTemplate = null, options = {}) {
         }
     }
     // 1. Structure (skeleton)
-    const folders = extractStructure(resolvedPath, resolvedPath, ignorePatterns);
+    const folders = fileTemplateConfig.folders && Array.isArray(fileTemplateConfig.folders)
+        ? fileTemplateConfig.folders
+        : extractStructure(resolvedPath, resolvedPath, ignorePatterns);
     // 2. Content Selection (Root only)
     const rootEntries = fs.readdirSync(resolvedPath, { withFileTypes: true })
         .filter(e => !shouldExclude(resolvedPath, path.join(resolvedPath, e.name), ignorePatterns))
@@ -250,52 +285,62 @@ export async function learn(sourcePath, updateTemplate = null, options = {}) {
         selectedFolders = copyFoldersResponse.selectedFolders;
     }
     const copy_files = [];
-    for (const f of selectedFiles) {
-        copy_files.push({ src: f, dest: f, substitute_variables: true });
+    if (fileTemplateConfig.copy_files && Array.isArray(fileTemplateConfig.copy_files)) {
+        copy_files.push(...fileTemplateConfig.copy_files);
     }
-    for (const d of selectedFolders) {
-        copy_files.push({ src: d, dest: d, substitute_variables: true });
+    else {
+        for (const f of selectedFiles) {
+            copy_files.push({ src: f, dest: f, substitute_variables: true });
+        }
+        for (const d of selectedFolders) {
+            copy_files.push({ src: d, dest: d, substitute_variables: true });
+        }
     }
     const templateConfig = {
         description: description,
         templateRoot: resolvedPath,
-        folders: folders.filter(f => selectedStructure.includes(f.name)),
+        folders: fileTemplateConfig.folders ? folders : folders.filter(f => selectedStructure.includes(f.name)),
         copy_files: copy_files,
         variables: variables.length > 0 ? variables : undefined
     };
     // Check for post_config scripts
-    const postConfigTasks = [];
-    const shPath = path.join(resolvedPath, 'post_config.sh');
-    const batPath = path.join(resolvedPath, 'post_config.bat');
-    if (fs.existsSync(shPath)) {
-        const lines = fs.readFileSync(shPath, 'utf-8').split('\n');
-        let currentDesc = '';
-        for (const line of lines) {
-            if (line.startsWith('echo "Running: ')) {
-                currentDesc = line.substring(15, line.length - 1).replace(/"$/, '');
-            }
-            else if (line.trim() && !line.startsWith('#') && !line.startsWith('echo ')) {
-                postConfigTasks.push({ command: line.trim(), description: currentDesc || line.trim() });
-                currentDesc = '';
-            }
-        }
+    let postConfigTasks = [];
+    if (fileTemplateConfig.post_config && Array.isArray(fileTemplateConfig.post_config)) {
+        postConfigTasks = [...fileTemplateConfig.post_config];
     }
-    else if (fs.existsSync(batPath)) {
-        const lines = fs.readFileSync(batPath, 'utf-8').split('\n');
-        let currentDesc = '';
-        for (const line of lines) {
-            if (line.startsWith('echo Running: ')) {
-                currentDesc = line.substring(14).trim();
+    else {
+        const shPath = path.join(resolvedPath, 'post_config.sh');
+        const batPath = path.join(resolvedPath, 'post_config.bat');
+        if (fs.existsSync(shPath)) {
+            const lines = fs.readFileSync(shPath, 'utf-8').split('\n');
+            let currentDesc = '';
+            for (const line of lines) {
+                if (line.startsWith('echo "Running: ')) {
+                    currentDesc = line.substring(15, line.length - 1).replace(/"$/, '');
+                }
+                else if (line.trim() && !line.startsWith('#') && !line.startsWith('echo ')) {
+                    postConfigTasks.push({ command: line.trim(), description: currentDesc || line.trim() });
+                    currentDesc = '';
+                }
             }
-            else if (line.trim() && !line.startsWith('::') && !line.startsWith('@echo') && !line.startsWith('echo ')) {
-                postConfigTasks.push({ command: line.trim(), description: currentDesc || line.trim() });
-                currentDesc = '';
+        }
+        else if (fs.existsSync(batPath)) {
+            const lines = fs.readFileSync(batPath, 'utf-8').split('\n');
+            let currentDesc = '';
+            for (const line of lines) {
+                if (line.startsWith('echo Running: ')) {
+                    currentDesc = line.substring(14).trim();
+                }
+                else if (line.trim() && !line.startsWith('::') && !line.startsWith('@echo') && !line.startsWith('echo ')) {
+                    postConfigTasks.push({ command: line.trim(), description: currentDesc || line.trim() });
+                    currentDesc = '';
+                }
             }
         }
     }
     if (postConfigTasks.length > 0) {
         templateConfig.post_config = postConfigTasks;
-        if (!options.json)
+        if (!options.json && !fileTemplateConfig.post_config)
             console.log(chalk.cyan(`Auto-detected ${postConfigTasks.length} post_config action(s) from script.`));
     }
     // Handle default_post_config tasks
@@ -353,7 +398,12 @@ export async function learn(sourcePath, updateTemplate = null, options = {}) {
             detectedExecutables.push(file);
         }
     }
-    if (detectedExecutables.length > 0) {
+    if (fileTemplateConfig.post_copy && Array.isArray(fileTemplateConfig.post_copy)) {
+        templateConfig.post_copy = fileTemplateConfig.post_copy;
+        const postCopySrcs = fileTemplateConfig.post_copy.map(f => f.src);
+        templateConfig.copy_files = templateConfig.copy_files?.filter(cf => !postCopySrcs.includes(cf.src));
+    }
+    else if (detectedExecutables.length > 0) {
         if (!options.json) {
             console.log(chalk.cyan("\nAuto-detected " + detectedExecutables.length + " executable file(s) at root:"));
             for (const file of detectedExecutables) {

package/dist/config.js

@@ -88,8 +88,30 @@ export function loadConfig() {
         process.exit(1);
     }
 }
+export function normalizeVariable(v) {
+    const result = { name: v.name };
+    if (v.prompt !== undefined)
+        result.prompt = v.prompt;
+    if (v.default !== undefined)
+        result.default = v.default;
+    if (v.required !== undefined)
+        result.required = v.required;
+    return result;
+}
 export function saveConfig(config) {
     ensureConfigDir();
+    // Normalize variable key ordering (forces 'name' to be first in serialized YAML)
+    if (config.variables && Array.isArray(config.variables)) {
+        config.variables = config.variables.map(normalizeVariable);
+    }
+    if (config.templates) {
+        for (const key of Object.keys(config.templates)) {
+            const template = config.templates[key];
+            if (template.variables && Array.isArray(template.variables)) {
+                template.variables = template.variables.map(normalizeVariable);
+            }
+        }
+    }
     const content = YAML.stringify(config);
     const tempPath = CONFIG_PATH + '.tmp';
     const backupPath = CONFIG_PATH + '.bak';

package/dist/index.js

@@ -38,6 +38,7 @@ program
 program
     .command('init [templateName] [destPath]')
     .description('Initialize a new project from a learned template')
+    .option('-f, --file <jsonPath>', 'Initialize directly from a JSON template file without adding it to local config')
     .option('--skip-post-config', 'Skip running post-config tasks')
     .option('--dry-run', 'Show what would be created without making changes')
     .option('-y, --yes', 'Automatically answer yes to prompts')

package/doc/configuration.md

@@ -42,6 +42,8 @@ When learning a template, `pt` scans the source directory for common patterns an
 
 Additionally, if `pt learn` finds a `post_config.sh` or `post_config.bat` file at the root of the directory, it will parse the scripts and automatically load the tasks into the `post_config` array.
 
+If the directory contains a `.pt-template.json` or `template.json` file with a `post_config` array, those tasks take precedence over shell script parsing. See [Usage Guide — JSON Template Config](usage.md#json-template-config-file-pt-templatejson) for the full JSON config format.
+
 ### The 80% Philosophy
 
 `pt` is designed to get you **80% of the way there** automatically. For complex templates, you are encouraged to:

package/doc/usage.md

@@ -20,6 +20,25 @@ pt learn /path/to/PROJECT --ignore=**/.godot/
 pt learn /path/to/PROJECT --name my_template --desc "My new template" --yes
 ```
 
+### Remote Template Learning
+
+`pt learn` supports learning templates directly from a remote Git repository or tarball archive by passing an `http://` or `https://` URL:
+
+```bash
+# Learn a template directly from a GitHub repository
+pt learn https://github.com/username/my-template
+
+# Learn a template from a Gitea repository
+pt learn https://gitea.example.com/username/my-template
+```
+
+#### How it works:
+1. **URL Translation:** If a GitHub or Gitea URL is provided, `pt` automatically translates the repository URL to its corresponding tarball download endpoint (e.g., `/archive/refs/heads/main.tar.gz`).
+2. **Download & Extraction:** The tool downloads the archive into a secure temporary folder and extracts it.
+3. **Template Discovery:** The extracted directory is scanned for metadata (`.pt-template.json`, `template.json`, `.info.md`, `post_config.sh`, `post_config.bat`) and variable placeholders (`{{ var }}`), matching local learn functionality exactly.
+4. **Save Config:** The template config (skeleton structure, files, variables) is saved to the local configuration, pointing to the temporary folder as the `templateRoot`.
+
+
 ### Automatic Variable Detection
 
 During `pt learn` or `pt update`, the tool automatically scans text files at the root and in the first-level subdirectories for variable placeholders using the `{{ variable_name }}` syntax. 
@@ -43,6 +62,25 @@ pt init <template_name> /path/to/new/PROJECT --dry-run
 
 # Non-interactive mode with variables (useful for an API or AI agents)
 pt init <template_name> /path/to/new/PROJECT --yes --vars project_name=foo,author=bar
+
+# Initialize directly from a JSON template file (no config.yaml registration)
+pt init /path/to/new/PROJECT --file my-template.json --yes
+```
+
+### Direct JSON Scaffolding (`--file`)
+
+The `--file` option allows you to scaffold a project directly from a JSON template file **without** registering it in your local `~/.pt/config.yaml`. This is ideal for:
+
+- One-off project creation from a shared template
+- CI/CD pipelines where you don't want to modify the user's config
+- Receiving a template JSON from a colleague and using it immediately
+
+```bash
+# The template name is read from the JSON's "name" field
+pt init ./new-project --file template.json --yes
+
+# With variable overrides
+pt init ./new-project --file template.json --yes --vars client=Acme,author=Jane
 ```
 
 ## Remove a template
@@ -86,11 +124,66 @@ For more details on how these are used, see the [Configuration Guide](configurat
 
 You can share your templates with others simply by sharing a directory (or a ZIP of it). When someone else runs `pt learn` on it, `pt` will automatically detect the following files at the root:
 
+- `.pt-template.json` or `template.json`: **Full template configuration** — name, description, variables (with prompts, defaults, required flags), folders, copy_files, post_config, and post_copy. This is the most complete and portable way to share templates.
 - `.info.md`: Used to automatically set the template's name (from the first `# Heading`) and description.
 - `post_config.sh` or `post_config.bat`: Parsed to automatically populate the `post_config` actions in the user's `config.yaml`.
 
+**Priority order:** `.pt-template.json` > `template.json` > `.info.md` > `post_config.sh`/`.bat`. JSON config files take precedence over `.info.md` for name/description and over shell scripts for post_config tasks.
+
 These files are also automatically generated at the root of a new project whenever you run `pt init`, making it trivial to initialize a project, zip it up, and share it with teammates as a fully-featured template!
 
+### JSON Template Config File (`.pt-template.json`)
+
+The JSON template config file is the recommended way to make a template directory fully self-describing and portable. Place it at the root of your template directory:
+
+```json
+{
+  "name": "my-web-app",
+  "description": "A Node.js web application with Express",
+  "variables": [
+    { "name": "project_name", "prompt": "Project name:", "default": "my-app", "required": true },
+    { "name": "author", "prompt": "Author name:", "default": "" }
+  ],
+  "folders": [
+    { "name": "src", "children": [] },
+    { "name": "tests", "children": [] }
+  ],
+  "copy_files": [
+    { "src": "package.json", "dest": "package.json", "substitute_variables": true },
+    { "src": "README.md", "dest": "README.md", "substitute_variables": true }
+  ],
+  "post_config": [
+    { "command": "git init", "description": "Initialize git repository" },
+    { "command": "npm install", "description": "Install dependencies" }
+  ],
+  "post_copy": [
+    { "src": "bin/start.sh", "dest": "bin/start.sh" }
+  ]
+}
+```
+
+When `pt learn` encounters this file, **all fields are used as pre-configured defaults**, skipping the corresponding interactive prompts. Any fields not specified in the JSON file will fall back to normal auto-detection (file scanning, executable detection, etc.).
+
+### Portable Template Round-Trip Workflow
+
+The complete workflow for sharing a fully portable template:
+
+```bash
+# 1. Export an existing template to JSON
+pt config my-template --json > .pt-template.json
+
+# 2. Place the JSON file at the root of your template directory
+cp .pt-template.json /path/to/template-dir/
+
+# 3. Share the directory (zip, git, etc.)
+
+# 4. Recipient learns the template — all metadata auto-detected
+pt learn /path/to/template-dir --yes
+
+# 5. Or scaffold directly without registering in config
+pt init ./new-project --file .pt-template.json --yes
+```
+
 ### JSON Export & Import
 
 For a more portable, text-based approach, you can export and import templates as JSON strings or files.
@@ -112,6 +205,12 @@ Or from a JSON string:
 pt add <template_name> '{"description":"My Template","files":{...}}'
 ```
 
+#### Direct JSON Scaffolding (no config registration)
+To scaffold a project directly from a JSON file without adding the template to your config:
+```bash
+pt init ./destination --file my_template.json --yes
+```
+
 #### Exporting Full Config
 To see your entire configuration (including all templates) in JSON format:
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@garyr/pt-cli",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "description": "Project Template CLI - Learn structures and initialize projects",
   "main": "dist/index.js",
   "bin": {
@@ -11,6 +11,7 @@
     "build": "tsc",
     "start": "tsx src/index.ts",
     "dev": "tsx src/index.ts",
+    "test": "node --import tsx --test tests/**/*.test.ts",
     "prepublishOnly": "npm run build",
     "build:linux": "bun build ./src/index.ts --compile --target=bun-linux-x64   --outfile ../BUILD/pt-cli/pt-linux",
     "build:macos": "bun build ./src/index.ts --compile --target=bun-darwin-x64  --outfile ../BUILD/pt-cli/pt-macos",
@@ -41,4 +42,4 @@
     "tsx": "^4.21.0",
     "typescript": "^5.6.0"
   }
-}
+}

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

@@ -17,20 +17,70 @@ As an agent equipped with this skill, you have the ability to rapidly scaffold,
    When a matching template exists, initialize it using the non-interactive flags.
    - **Command:** `pt init <template_name> <destination_path> --yes`
    - If the template requires variables, pass them: `pt init <template_name> <destination_path> --yes --vars key1=value1,key2=value2`
+   - **Direct JSON scaffolding:** To scaffold from a JSON template file without registering it in `config.yaml`:
+     `pt init <destination_path> --file <json_path> --yes`
    - *Never* run `pt init` without `--yes`, as interactive prompts will block you.
    - Note any errors from auto-executed post-config tasks (like `npm install` failing) and correct them if necessary.
-   - Note any errors from auto-executed post-config tasks (like `npm install` failing) and correct them if necessary.
 
 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!
    - **Command:** `pt learn <source_path> --name <template_name> --desc "<Description>" --yes`
+   - **Remote Templates:** You can also 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.
    - **Automatic Variable Detection:** `pt learn` and `pt update` automatically scan text files (at root and one level deep) for `{{ variable_name }}` placeholders. You can add these to files (e.g., `README.md`, `.makerc`) and run `pt update <template> . --yes` to have them registered as template variables without manual configuration.
+   - **JSON Template Config:** If the source directory contains a `.pt-template.json` or `template.json` file, `pt learn` will auto-detect name, description, variables, folders, copy_files, post_config, and post_copy from it — skipping the corresponding interactive prompts.
 
 4. **Template Maintenance (`pt rm`):**
    If a template is obsolete or requested for deletion, use `pt rm`.
    - **Command:** `pt rm <template_name> --yes`
 
+## Template Sharing & Portability
+
+Templates are designed to be fully portable. There are two approaches to sharing:
+
+### 1. Directory-based Sharing (recommended for complete templates)
+
+Place a `.pt-template.json` at the root of your template directory. This file can include all template metadata:
+
+```json
+{
+  "name": "my-template",
+  "description": "Description of the template",
+  "variables": [
+    { "name": "project_name", "prompt": "Project name:", "default": "my-app", "required": true }
+  ],
+  "post_config": [
+    { "command": "git init", "description": "Initialize git" }
+  ]
+}
+```
+
+When someone runs `pt learn /path/to/shared-dir --yes`, all metadata is auto-detected from this file.
+
+**Priority order:** `.pt-template.json` > `template.json` > `.info.md` > `post_config.sh`/`.bat`
+
+### 2. JSON Export/Import (for config-only sharing)
+
+```bash
+# Export a template to JSON
+pt config my-template --json > my-template.json
+
+# Import into another user's config
+pt add my-template --file my-template.json
+
+# Or scaffold directly without importing
+pt init ./new-project --file my-template.json --yes
+```
+
+### Round-trip Workflow
+
+The complete portable template workflow:
+1. `pt config my-template --json > .pt-template.json` — export config
+2. Copy `.pt-template.json` into the template source directory
+3. Share the directory (zip, git repo, etc.)
+4. Recipient: `pt learn /path/to/shared-dir --yes` — auto-detects everything
+
 ## Default Post-Config
 
 Default post-config tasks are stored in `~/.pt/config.yaml` under `default_post_config`. They are used as suggestions during `pt learn` to apply to the newly created template. Each task supports:

package/src/commands/initCommand.ts

@@ -1,7 +1,7 @@
 import fs from 'fs';
 import path from 'path';
 import inquirer from 'inquirer';
-import { loadConfig, FolderNode, sanitizePath } from '../config.js';
+import { loadConfig, FolderNode, sanitizePath, TemplateConfig } from '../config.js';
 import chalk from 'chalk';
 import { processCopyFiles } from '../substitute.js';
 import { execSync } from 'child_process';
@@ -11,47 +11,69 @@ export interface InitOptions {
   dryRun?: boolean;
   yes?: boolean;
   vars?: string;
+  file?: string;
 }
 
 export async function init(targetName: string | undefined, destPath: string | undefined, options: InitOptions = {}) {
   const config = loadConfig();
 
   let typeName: string | undefined = targetName;
+  let dest: string | undefined = destPath;
+  let template: TemplateConfig;
 
-  // If no name provided, list templates
-  if (!typeName) {
-    const names = Object.keys(config.templates);
-    if (names.length === 0) {
-      console.log(chalk.red("No templates found. Run 'pt learn <path>' first."));
-      return;
+  if (options.file) {
+    // If direct template file is specified, targetName could be the destPath if destPath is omitted
+    if (typeName && !dest) {
+      dest = typeName;
+      typeName = undefined;
     }
 
-    if (options.yes) {
-      console.error(chalk.red("No project type specified and running in non-interactive mode."));
+    try {
+      const fileContent = fs.readFileSync(options.file, 'utf-8');
+      template = JSON.parse(fileContent);
+    } catch (e) {
+      console.error(chalk.red(`Error: Failed to read/parse template file "${options.file}": ${(e as Error).message}`));
       process.exit(1);
     }
-    const { selected } = await inquirer.prompt({
-      type: 'list',
-      name: 'selected',
-      message: 'Select Project Type:',
-      loop: false,
-      theme: {
-        icon: {
-          cursor: chalk.green('[x] ')
-        }
-      },
-      choices: names.map(n => ({ name: n, value: n }))
-    });
-    typeName = selected;
-  }
 
-  const template = config.templates[typeName!];
-  if (!template) {
-    console.error(chalk.red(`Template "${typeName}" not found.`));
-    process.exit(1);
+    if (!typeName) {
+      typeName = (template as any).name || 'custom-template';
+    }
+  } else {
+    // If no name provided, list templates
+    if (!typeName) {
+      const names = Object.keys(config.templates);
+      if (names.length === 0) {
+        console.log(chalk.red("No templates found. Run 'pt learn <path>' first."));
+        return;
+      }
+
+      if (options.yes) {
+        console.error(chalk.red("No project type specified and running in non-interactive mode."));
+        process.exit(1);
+      }
+      const { selected } = await inquirer.prompt({
+        type: 'list',
+        name: 'selected',
+        message: 'Select Project Type:',
+        loop: false,
+        theme: {
+          icon: {
+            cursor: chalk.green('[x] ')
+          }
+        },
+        choices: names.map(n => ({ name: n, value: n }))
+      });
+      typeName = selected;
+    }
+
+    template = config.templates[typeName!];
+    if (!template) {
+      console.error(chalk.red(`Template "${typeName}" not found.`));
+      process.exit(1);
+    }
   }
 
-  let dest: string | undefined = destPath;
   if (!dest) {
     if (options.yes) {
       console.error(chalk.red("No destination path specified and running in non-interactive mode."));

package/src/commands/learnCommand.ts

@@ -34,6 +34,25 @@ export async function learn(sourcePath: string, updateTemplate: string | null =
   const config = loadConfig();
   const existingNames = getTemplateNames(config);
 
+  // Check for template configuration JSON file (.pt-template.json or template.json)
+  let fileTemplateConfig: Partial<TemplateConfig> & { name?: string } = {};
+  const jsonConfigPaths = [
+    path.join(resolvedPath, '.pt-template.json'),
+    path.join(resolvedPath, 'template.json')
+  ];
+  for (const jPath of jsonConfigPaths) {
+    if (fs.existsSync(jPath)) {
+      try {
+        const fileContent = fs.readFileSync(jPath, 'utf-8');
+        fileTemplateConfig = JSON.parse(fileContent);
+        if (!options.json) console.log(chalk.cyan(`Auto-detected template configurations from ${path.basename(jPath)}`));
+        break;
+      } catch (e) {
+        console.warn(chalk.yellow(`Warning: Failed to parse ${path.basename(jPath)}: ${(e as Error).message}`));
+      }
+    }
+  }
+
   // Check for .info.md
   let infoName = '';
   let infoDesc = '';
@@ -60,6 +79,9 @@ export async function learn(sourcePath: string, updateTemplate: string | null =
   } else {
     if (options.name) {
       targetName = options.name;
+    } else if (fileTemplateConfig.name) {
+      targetName = fileTemplateConfig.name;
+      if (!options.json) console.log(chalk.cyan(`Auto-detected template name from JSON: ${targetName}`));
     } else if (infoName) {
       targetName = infoName;
       if (!options.json) console.log(chalk.cyan(`Auto-detected template name from .info.md: ${targetName}`));
@@ -106,7 +128,10 @@ export async function learn(sourcePath: string, updateTemplate: string | null =
       }
     }
   } else {
-    if (infoDesc) {
+    if (fileTemplateConfig.description) {
+      description = fileTemplateConfig.description;
+      if (!options.json) console.log(chalk.cyan(`Auto-detected template description from JSON: ${description}`));
+    } else if (infoDesc) {
       description = infoDesc;
       if (!options.json) console.log(chalk.cyan(`Auto-detected template description from .info.md: ${description}`));
     } else if (options.yes || options.json) {
@@ -136,6 +161,8 @@ export async function learn(sourcePath: string, updateTemplate: string | null =
   // Merge with existing variables if update
   if (isUpdate && config.templates[updateTemplate].variables) {
     variables = [...config.templates[updateTemplate].variables];
+  } else if (fileTemplateConfig.variables && Array.isArray(fileTemplateConfig.variables)) {
+    variables = [...fileTemplateConfig.variables];
   }
 
   // Add detected variables if not already present
@@ -194,7 +221,9 @@ export async function learn(sourcePath: string, updateTemplate: string | null =
   }
 
   // 1. Structure (skeleton)
-  const folders = extractStructure(resolvedPath, resolvedPath, ignorePatterns);
+  const folders = fileTemplateConfig.folders && Array.isArray(fileTemplateConfig.folders)
+    ? fileTemplateConfig.folders
+    : extractStructure(resolvedPath, resolvedPath, ignorePatterns);
 
   // 2. Content Selection (Root only)
   const rootEntries = fs.readdirSync(resolvedPath, { withFileTypes: true })
@@ -270,51 +299,59 @@ export async function learn(sourcePath: string, updateTemplate: string | null =
   }
 
   const copy_files: CopyFileEntry[] = [];
-  for (const f of selectedFiles) {
-    copy_files.push({ src: f, dest: f, substitute_variables: true });
-  }
-  for (const d of selectedFolders) {
-    copy_files.push({ src: d, dest: d, substitute_variables: true });
+  if (fileTemplateConfig.copy_files && Array.isArray(fileTemplateConfig.copy_files)) {
+    copy_files.push(...fileTemplateConfig.copy_files);
+  } else {
+    for (const f of selectedFiles) {
+      copy_files.push({ src: f, dest: f, substitute_variables: true });
+    }
+    for (const d of selectedFolders) {
+      copy_files.push({ src: d, dest: d, substitute_variables: true });
+    }
   }
 
   const templateConfig: TemplateConfig = {
     description: description,
     templateRoot: resolvedPath,
-    folders: folders.filter(f => selectedStructure.includes(f.name)),
+    folders: fileTemplateConfig.folders ? folders : folders.filter(f => selectedStructure.includes(f.name)),
     copy_files: copy_files,
     variables: variables.length > 0 ? variables : undefined
   };
 
   // Check for post_config scripts
-  const postConfigTasks: PostConfigTask[] = [];
-  const shPath = path.join(resolvedPath, 'post_config.sh');
-  const batPath = path.join(resolvedPath, 'post_config.bat');
-  if (fs.existsSync(shPath)) {
-    const lines = fs.readFileSync(shPath, 'utf-8').split('\n');
-    let currentDesc = '';
-    for (const line of lines) {
-      if (line.startsWith('echo "Running: ')) {
-        currentDesc = line.substring(15, line.length - 1).replace(/"$/, '');
-      } else if (line.trim() && !line.startsWith('#') && !line.startsWith('echo ')) {
-        postConfigTasks.push({ command: line.trim(), description: currentDesc || line.trim() });
-        currentDesc = '';
+  let postConfigTasks: PostConfigTask[] = [];
+  if (fileTemplateConfig.post_config && Array.isArray(fileTemplateConfig.post_config)) {
+    postConfigTasks = [...fileTemplateConfig.post_config];
+  } else {
+    const shPath = path.join(resolvedPath, 'post_config.sh');
+    const batPath = path.join(resolvedPath, 'post_config.bat');
+    if (fs.existsSync(shPath)) {
+      const lines = fs.readFileSync(shPath, 'utf-8').split('\n');
+      let currentDesc = '';
+      for (const line of lines) {
+        if (line.startsWith('echo "Running: ')) {
+          currentDesc = line.substring(15, line.length - 1).replace(/"$/, '');
+        } else if (line.trim() && !line.startsWith('#') && !line.startsWith('echo ')) {
+          postConfigTasks.push({ command: line.trim(), description: currentDesc || line.trim() });
+          currentDesc = '';
+        }
       }
-    }
-  } else if (fs.existsSync(batPath)) {
-    const lines = fs.readFileSync(batPath, 'utf-8').split('\n');
-    let currentDesc = '';
-    for (const line of lines) {
-      if (line.startsWith('echo Running: ')) {
-        currentDesc = line.substring(14).trim();
-      } else if (line.trim() && !line.startsWith('::') && !line.startsWith('@echo') && !line.startsWith('echo ')) {
-        postConfigTasks.push({ command: line.trim(), description: currentDesc || line.trim() });
-        currentDesc = '';
+    } else if (fs.existsSync(batPath)) {
+      const lines = fs.readFileSync(batPath, 'utf-8').split('\n');
+      let currentDesc = '';
+      for (const line of lines) {
+        if (line.startsWith('echo Running: ')) {
+          currentDesc = line.substring(14).trim();
+        } else if (line.trim() && !line.startsWith('::') && !line.startsWith('@echo') && !line.startsWith('echo ')) {
+          postConfigTasks.push({ command: line.trim(), description: currentDesc || line.trim() });
+          currentDesc = '';
+        }
       }
     }
   }
   if (postConfigTasks.length > 0) {
     templateConfig.post_config = postConfigTasks;
-    if (!options.json) console.log(chalk.cyan(`Auto-detected ${postConfigTasks.length} post_config action(s) from script.`));
+    if (!options.json && !fileTemplateConfig.post_config) console.log(chalk.cyan(`Auto-detected ${postConfigTasks.length} post_config action(s) from script.`));
   }
 
   // Handle default_post_config tasks
@@ -374,7 +411,11 @@ export async function learn(sourcePath: string, updateTemplate: string | null =
     }
   }
 
-  if (detectedExecutables.length > 0) {
+  if (fileTemplateConfig.post_copy && Array.isArray(fileTemplateConfig.post_copy)) {
+    templateConfig.post_copy = fileTemplateConfig.post_copy;
+    const postCopySrcs = fileTemplateConfig.post_copy.map(f => f.src);
+    templateConfig.copy_files = templateConfig.copy_files?.filter(cf => !postCopySrcs.includes(cf.src));
+  } else if (detectedExecutables.length > 0) {
     if (!options.json) {
       console.log(chalk.cyan("\nAuto-detected " + detectedExecutables.length + " executable file(s) at root:"));
       for (const file of detectedExecutables) {

package/src/config.ts

@@ -150,8 +150,30 @@ export function loadConfig(): PtConfig {
   }
 }
 
+export function normalizeVariable(v: TemplateVariable): TemplateVariable {
+  const result: any = { name: v.name };
+  if (v.prompt !== undefined) result.prompt = v.prompt;
+  if (v.default !== undefined) result.default = v.default;
+  if (v.required !== undefined) result.required = v.required;
+  return result;
+}
+
 export function saveConfig(config: PtConfig) {
   ensureConfigDir();
+
+  // Normalize variable key ordering (forces 'name' to be first in serialized YAML)
+  if (config.variables && Array.isArray(config.variables)) {
+    config.variables = config.variables.map(normalizeVariable);
+  }
+  if (config.templates) {
+    for (const key of Object.keys(config.templates)) {
+      const template = config.templates[key];
+      if (template.variables && Array.isArray(template.variables)) {
+        template.variables = template.variables.map(normalizeVariable);
+      }
+    }
+  }
+
   const content = YAML.stringify(config);
   const tempPath = CONFIG_PATH + '.tmp';
   const backupPath = CONFIG_PATH + '.bak';

package/src/index.ts

@@ -49,6 +49,7 @@ program
 program
   .command('init [templateName] [destPath]')
   .description('Initialize a new project from a learned template')
+  .option('-f, --file <jsonPath>', 'Initialize directly from a JSON template file without adding it to local config')
   .option('--skip-post-config', 'Skip running post-config tasks')
   .option('--dry-run', 'Show what would be created without making changes')
   .option('-y, --yes', 'Automatically answer yes to prompts')

package/tests/config.test.ts

@@ -0,0 +1,98 @@
+import { test, before, after } from 'node:test';
+import assert from 'node:assert';
+import fs from 'fs';
+import path from 'path';
+
+// Force a temporary home directory for testing before importing anything from the CLI
+const testHome = path.join(process.cwd(), '.test-home-config');
+process.env.HOME = testHome;
+
+import { normalizeVariable, saveConfig, loadConfig, PtConfig, CONFIG_PATH } from '../src/config.js';
+
+test('normalizeVariable key ordering', () => {
+  const variableInput = {
+    required: true,
+    default: 'my-default',
+    prompt: 'Enter variable:',
+    name: 'varName'
+  };
+
+  const normalized = normalizeVariable(variableInput);
+  
+  // Verify that name is the first key in the returned object
+  const keys = Object.keys(normalized);
+  assert.strictEqual(keys[0], 'name', 'The "name" key must be first');
+  assert.deepStrictEqual(keys, ['name', 'prompt', 'default', 'required']);
+});
+
+test('saveConfig and loadConfig roundtrip', () => {
+  // Clean up any existing test files
+  if (fs.existsSync(CONFIG_PATH)) {
+    fs.unlinkSync(CONFIG_PATH);
+  }
+  const backupPath = CONFIG_PATH + '.bak';
+  if (fs.existsSync(backupPath)) {
+    fs.unlinkSync(backupPath);
+  }
+
+  const testConfig: PtConfig = {
+    version: '1.0.0',
+    templates: {
+      'test-tpl': {
+        description: 'Test Template Description',
+        folders: [
+          { name: 'src', info: 'source folder' }
+        ],
+        variables: [
+          {
+            required: true,
+            default: 'hello',
+            prompt: 'Prompt:',
+            name: 'myVar'
+          }
+        ]
+      }
+    }
+  };
+
+  // Save the config
+  saveConfig(testConfig);
+
+  // Assert CONFIG_PATH exists and has been created
+  assert.ok(fs.existsSync(CONFIG_PATH), 'Config file should be created');
+
+  // Verify key order in YAML string
+  const yamlContent = fs.readFileSync(CONFIG_PATH, 'utf-8');
+  assert.ok(yamlContent.includes('name: myVar'), 'Should contain myVar variable');
+  
+  // Load the config back
+  const loaded = loadConfig();
+  assert.strictEqual(loaded.version, '1.0.0');
+  assert.ok(loaded.templates['test-tpl']);
+  assert.strictEqual(loaded.templates['test-tpl'].description, 'Test Template Description');
+  
+  const loadedVar = loaded.templates['test-tpl'].variables?.[0];
+  assert.ok(loadedVar);
+  assert.strictEqual(loadedVar.name, 'myVar');
+
+  // Test atomic backup behavior: saving again should create a backup
+  saveConfig({
+    ...testConfig,
+    version: '1.0.1'
+  });
+  
+  assert.ok(fs.existsSync(backupPath), 'Backup file .bak should exist after a second save');
+  const backupContent = fs.readFileSync(backupPath, 'utf-8');
+  assert.ok(backupContent.includes("version: 1.0.0") || backupContent.includes("version: '1.0.0'"), 'Backup should contain previous version');
+
+  // Clean up
+  if (fs.existsSync(CONFIG_PATH)) {
+    fs.unlinkSync(CONFIG_PATH);
+  }
+  if (fs.existsSync(backupPath)) {
+    fs.unlinkSync(backupPath);
+  }
+  if (fs.existsSync(testHome)) {
+    fs.rmdirSync(testHome);
+  }
+});

package/tests/init.test.ts

@@ -0,0 +1,77 @@
+import { test } from 'node:test';
+import assert from 'node:assert';
+import fs from 'fs';
+import path from 'path';
+
+// Force a temporary home directory for testing before importing anything from the CLI
+const testHome = path.join(process.cwd(), '.test-home-init');
+process.env.HOME = testHome;
+
+import { init } from '../src/commands/initCommand.js';
+
+test('direct JSON template initialization via --file', async () => {
+  const jsonFilePath = path.join(process.cwd(), 'test-direct-template.json');
+  const projectDest = path.join(process.cwd(), 'test-scaffolded-project');
+
+  // Ensure clean state
+  if (fs.existsSync(jsonFilePath)) {
+    fs.unlinkSync(jsonFilePath);
+  }
+  if (fs.existsSync(projectDest)) {
+    fs.rmSync(projectDest, { recursive: true, force: true });
+  }
+
+  // Create a mock template JSON configuration
+  const mockTemplate = {
+    name: 'direct-json-test',
+    description: 'A mock template for direct JSON scaffolding test',
+    folders: [
+      {
+        name: 'src',
+        info: 'contains sources',
+        children: [
+          { name: 'components', info: 'reusable components' },
+          { name: 'utils', info: 'utility functions' }
+        ]
+      },
+      {
+        name: 'docs',
+        info: 'documentation folder'
+      }
+    ]
+  };
+
+  fs.writeFileSync(jsonFilePath, JSON.stringify(mockTemplate, null, 2));
+
+  // Run the init command with the --file option
+  // targetName (1st arg) is omitted/undefined, destPath (2nd arg) is our projectDest, file option is provided
+  await init(undefined, projectDest, {
+    file: jsonFilePath,
+    yes: true,
+    skipPostConfig: true
+  });
+
+  // Verify structure was created successfully
+  assert.ok(fs.existsSync(projectDest), 'Project destination folder should exist');
+  assert.ok(fs.existsSync(path.join(projectDest, 'src')), 'src directory should exist');
+  assert.ok(fs.existsSync(path.join(projectDest, 'src/components')), 'src/components directory should exist');
+  assert.ok(fs.existsSync(path.join(projectDest, 'src/utils')), 'src/utils directory should exist');
+  assert.ok(fs.existsSync(path.join(projectDest, 'docs')), 'docs directory should exist');
+
+  // Verify metadata file .info.md was created
+  assert.ok(fs.existsSync(path.join(projectDest, '.info.md')), '.info.md file should exist');
+  const infoContent = fs.readFileSync(path.join(projectDest, '.info.md'), 'utf-8');
+  assert.ok(infoContent.includes('direct-json-test'), 'Should contain template name');
+  assert.ok(infoContent.includes('mock template'), 'Should contain description');
+
+  // Clean up
+  if (fs.existsSync(jsonFilePath)) {
+    fs.unlinkSync(jsonFilePath);
+  }
+  if (fs.existsSync(projectDest)) {
+    fs.rmSync(projectDest, { recursive: true, force: true });
+  }
+  if (fs.existsSync(testHome)) {
+    fs.rmSync(testHome, { recursive: true, force: true });
+  }
+});