@garyr/pt-cli 0.25.0

package/README.md

@@ -0,0 +1,112 @@
+# pt - Project Template CLI
+
+A CLI tool to record directory structures as templates and initialize new projects from them.
+
+```mermaid
+graph LR
+    subgraph Inputs ["Source & Configuration"]
+        Existing[Existing Project]
+        Config[(Template Config)]
+    end
+
+    Engine[[pt-cli]]
+
+    subgraph Outputs ["Generated Scaffolding"]
+        RSA[Replicated Structure A]
+        RSB[Replicated Structure B]
+    end
+
+    %% Flow logic
+    Existing -- Learn --> Engine
+    Config -- Read/Write --> Engine
+    Engine -- Initialize --> RSA
+    Engine -- Initialize --> RSB
+    
+    %% Separate the Update logic to avoid crossing lines
+    Existing -. Update .-> Engine
+
+    style Engine fill:#f9f,stroke:#333,stroke-width:2px,color:#000
+```
+
+## The Pipeline Benefit
+
+`pt-cli` is built to reduce boilerplate setup and ensure consistency across your workspaces. In a production pipeline, standardization is key to lowering the friction of cognitive load. `pt` helps by:
+
+- **Instantly replicating proven architectures:** Stop recreating folder structures manually. `pt learn` saves the shape of any project.
+- **Automating the setup grind:** With post-config tasks, `pt init` can run commands like `npm install`, `git init`, or setup python virtual environments for you.
+- **Global post-config:** Configure shared tasks (e.g. `git init`, `git lfs install`) once in `~/.pt/config.yaml` and have them apply to every new project automatically.
+- **Agentic automation:** Fully supports headless operation via non-interactive flags and includes a skill for integration with AI agents.
+- **File copying & templating:** Beyond directories, it allows injecting variables into key files (`package.json`, `README.md`, etc.) and automatically ports over executable scripts.
+
+## Features at a Glance
+
+- Learn any directory structure and save it as a reusable template
+- 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`
+- 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
+- Fully supports non-interactive mode (`--yes`, `--vars`) for AI agent automation
+
+## Quick Start
+
+### Installation
+
+```bash
+# Clone this repository
+cd pt-cli
+npm install
+npm run build
+
+# Link for global use
+npm link
+```
+
+### Basic Commands
+
+```bash
+# Learn an existing project structure
+pt learn /path/to/PROJECT
+
+# Scaffold a new project from a template
+pt init <template_name> /path/to/NEW_PROJECT
+
+# List available templates and configurations
+pt config
+
+# Export an existing template as JSON
+pt config my-template --json > my-template.json
+
+# Import a template from JSON
+pt add my-new-template --file my-new-template.json
+```
+
+## Documentation
+
+- [Detailed Usage](doc/usage.md) - Learn, Initialize, Update, and Remove commands.
+- [Configuration Guide](doc/configuration.md) - Template variables, post-config tasks, file copying, and more.
+- [Exclusions](doc/exclusions.md) - Learn about default ignored files and how to set custom patterns.
+
+## Development
+
+### Project Structure
+
+- `src/index.ts`: Entry point and command registration.
+- `src/commands/`: Individual command handler modules.
+- `src/config.ts`: Configuration loading, saving, and type definitions.
+
+### Technical Notes
+
+- **ESM Migration**: The project is now pure ESM. All internal imports must use the `.js` extension.
+- **Development Tooling**: Use `tsx` for running `.ts` files directly (`npm run dev`).
+- **Building**: Use `tsc` to compile to `dist/`.
+
+## Agent Integration
+
+`pt-cli` is compatible with AI agents. By utilizing the non-interactive flags (`--yes`, `--vars`, `--name`, `--desc`), agents can autonomously scaffold and learn projects without hanging on interactive terminal prompts.
+
+An official agent skill is included in this repository: [`skills/agency-pt-operator/SKILL.md`](skills/agency-pt-operator/SKILL.md).
+
+Equipping your agent with this skill allows it to automatically use `pt-cli` to lay down standardized boilerplate and capture new architectures you develop together.

package/dist/commands/addCommand.js

@@ -0,0 +1,37 @@
+import fs from 'fs';
+import path from 'path';
+import chalk from 'chalk';
+import { loadConfig, saveConfig } from '../config.js';
+export function addCommand(name, jsonStr, options = {}) {
+    const config = loadConfig();
+    try {
+        let data;
+        if (options.file) {
+            const filePath = path.resolve(options.file);
+            data = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+        }
+        else if (jsonStr) {
+            data = JSON.parse(jsonStr);
+        }
+        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
+        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.'));
+            process.exit(1);
+        }
+        config.templates[name] = data;
+        saveConfig(config);
+        console.log(chalk.green(`✓ Template "${name}" saved successfully.`));
+    }
+    catch (e) {
+        const error = e;
+        console.error(chalk.red(`Failed to parse template JSON: ${error.message}`));
+        process.exit(1);
+    }
+}

package/dist/commands/configCommand.js

@@ -0,0 +1,96 @@
+import chalk from 'chalk';
+import { loadConfig, getTemplateNames, CONFIG_PATH } from '../config.js';
+export function configCommand(templateName, options = {}) {
+    const config = loadConfig();
+    if (options.json) {
+        if (templateName) {
+            if (config.templates && config.templates[templateName]) {
+                const output = {
+                    name: templateName,
+                    ...config.templates[templateName]
+                };
+                console.log(JSON.stringify(output, null, 2));
+            }
+            else {
+                console.error(chalk.red(`Error: Template "${templateName}" not found.`));
+                process.exit(1);
+            }
+        }
+        else {
+            console.log(JSON.stringify(config, null, 2));
+        }
+        return;
+    }
+    const names = getTemplateNames(config);
+    console.log(chalk.cyan('Config Location:'), CONFIG_PATH);
+    console.log(chalk.cyan('\nLearned Templates:'));
+    if (names.length === 0) {
+        console.log(chalk.gray('  (none)'));
+    }
+    else {
+        for (const name of names) {
+            const t = config.templates[name];
+            if (!t)
+                continue;
+            console.log(chalk.white(`  - ${name}`), chalk.gray(`(${t.description})`));
+            if (t.templateRoot) {
+                console.log(chalk.gray(`      Source: ${t.templateRoot}`));
+            }
+            if (t.post_config && t.post_config.length > 0) {
+                console.log(chalk.cyan('      Post-config:'));
+                for (const task of t.post_config) {
+                    const cmd = task.command || task.script || '(unknown)';
+                    const typeFilter = task.type ? ` [type: ${task.type}]` : '';
+                    console.log(chalk.gray(`        - ${cmd}${typeFilter}`));
+                }
+            }
+            if (t.post_copy && t.post_copy.length > 0) {
+                console.log(chalk.cyan('      post_copy:'));
+                for (const f of t.post_copy) {
+                    console.log(chalk.gray(`        - ${f.src} → ${(f.dest || f.src)}`));
+                }
+            }
+        }
+    }
+    // Show global ignore patterns
+    if (config.ignore && config.ignore.length > 0) {
+        console.log(chalk.cyan('\nIgnore Patterns (pt learn):'));
+        for (const p of config.ignore) {
+            console.log(chalk.gray(`  - ${p}`));
+        }
+    }
+    // Show default post-config tasks
+    if (config.default_post_config && config.default_post_config.length > 0) {
+        console.log(chalk.cyan('\nDefault Post-Config Tasks:'));
+        for (const task of config.default_post_config) {
+            const cmd = task.command || task.script || '(unknown)';
+            const desc = task.description ? ` — ${task.description}` : '';
+            const checked = task.checked !== false ? '[default: on]' : '[default: off]';
+            const typeFilter = task.type ? ` [type: ${task.type}]` : '';
+            console.log(chalk.gray(`  - ${cmd}${desc}`));
+            console.log(chalk.gray(`    ${checked}${typeFilter}`));
+        }
+    }
+    // Show global variables
+    if (config.variables && config.variables.length > 0) {
+        console.log(chalk.cyan('\nGlobal Variables:'));
+        for (const v of config.variables) {
+            console.log(chalk.white(`  - ${v.name}:`), chalk.gray(v.default || '(no default)'));
+            if (v.prompt)
+                console.log(chalk.gray(`    Prompt: ${v.prompt}`));
+            if (v.required)
+                console.log(chalk.yellow(`    [Required]`));
+        }
+    }
+    console.log(chalk.cyan('\nExample post-config in config.yaml:'));
+    console.log(chalk.gray(`
+  my_template:
+    description: "My standard web project"
+    post_config:
+      - command: "git init"
+        description: "Initialize git repository"
+      - command: "npm install"
+        description: "Install npm dependencies"
+        type: "javascript"
+`));
+}

package/dist/commands/ignoreCommand.js

@@ -0,0 +1,12 @@
+import { loadConfig, saveConfig } from '../config.js';
+export function ignoreCommand(patterns, options = {}) {
+    const config = loadConfig();
+    if (options.set) {
+        config.ignore = patterns ? patterns.split(',').map((s) => s.trim()).filter((s) => s !== '') : [];
+        saveConfig(config);
+        console.log('Ignore patterns updated:', config.ignore);
+    }
+    else {
+        console.log('Current ignore patterns:', config.ignore || []);
+    }
+}

package/dist/commands/initCommand.js

@@ -0,0 +1,294 @@
+import fs from 'fs';
+import path from 'path';
+import inquirer from 'inquirer';
+import { loadConfig } from '../config.js';
+import chalk from 'chalk';
+import { processCopyFiles } from '../substitute.js';
+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;
+        }
+        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;
+    }
+    const 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."));
+            process.exit(1);
+        }
+        const { name } = await inquirer.prompt({
+            type: 'input',
+            name: 'name',
+            message: 'Project path/folder name:'
+        });
+        dest = name;
+    }
+    const resolvedDest = path.resolve(dest);
+    if (fs.existsSync(resolvedDest) && !options.dryRun) {
+        console.error(chalk.red(`Error: Destination "${resolvedDest}" already exists.`));
+        process.exit(1);
+    }
+    if (options.dryRun) {
+        console.log(chalk.yellow(`\n[DRY RUN] Initializing project "${template.description}" at: ${resolvedDest}`));
+    }
+    else {
+        console.log(chalk.cyan(`\nInitializing project "${template.description}" at: ${resolvedDest}`));
+    }
+    // Handle Variables
+    let variables = {};
+    if (template.variables && template.variables.length > 0) {
+        if (options.vars) {
+            // Parse --vars "key=val,key2=val2"
+            const pairs = options.vars.split(',').map((p) => p.trim());
+            for (const pair of pairs) {
+                const [k, ...v] = pair.split('=');
+                if (k && v.length > 0) {
+                    variables[k.trim()] = v.join('=').trim();
+                }
+            }
+        }
+        if (!options.yes) {
+            // Prompt for any missing variables
+            for (const v of template.variables) {
+                if (!variables[v.name]) {
+                    const answer = await inquirer.prompt({
+                        type: 'input',
+                        name: v.name,
+                        message: v.prompt || `Enter ${v.name}:`,
+                        default: v.default || ''
+                    });
+                    variables[v.name] = answer[v.name];
+                }
+            }
+        }
+        else {
+            // Non-interactive mode: check required
+            for (const v of template.variables) {
+                if (!variables[v.name]) {
+                    if (v.required) {
+                        console.error(chalk.red(`Error: Variable "${v.name}" is required but was not provided in non-interactive mode. Use --vars ${v.name}=value`));
+                        process.exit(1);
+                    }
+                    else {
+                        variables[v.name] = v.default || '';
+                    }
+                }
+            }
+        }
+    }
+    // 1. Create structure
+    createStructure(resolvedDest, template.folders, options.dryRun);
+    // Check if templateRoot exists (if it's defined)
+    const templateRootExists = template.templateRoot && fs.existsSync(template.templateRoot);
+    if (template.templateRoot && !templateRootExists) {
+        console.warn(chalk.yellow(`\nWarning: Template source directory not found: ${template.templateRoot}`));
+        console.warn(chalk.gray("Folder structure created, but files/boilerplate will be skipped."));
+    }
+    // 2. Process copy_files
+    if (template.copy_files && templateRootExists) {
+        if (options.dryRun)
+            console.log(chalk.yellow("[DRY RUN] Processing copy_files..."));
+        else
+            console.log(chalk.cyan("Processing copy_files..."));
+        await processCopyFiles(template.templateRoot, resolvedDest, template, variables, options.dryRun);
+    }
+    // 3. Process post_copy (executable scripts)
+    if (template.post_copy && templateRootExists) {
+        if (options.dryRun)
+            console.log(chalk.yellow("[DRY RUN] Processing post_copy..."));
+        else
+            console.log(chalk.cyan("Processing post_copy..."));
+        for (const file of template.post_copy) {
+            const srcPath = path.join(template.templateRoot, file.src);
+            const destPath = path.join(resolvedDest, file.dest || file.src);
+            if (fs.existsSync(srcPath)) {
+                if (options.dryRun) {
+                    console.log(chalk.gray(`  [DRY RUN] Would copy ${file.src} → ${file.dest || file.src}`));
+                    const ext = path.extname(file.src);
+                    if (['.sh', '.py', '.bash', '.bat'].includes(ext)) {
+                        console.log(chalk.gray(`  [DRY RUN] Would chmod +x ${file.dest || file.src}`));
+                    }
+                    continue;
+                }
+                const fileContent = fs.readFileSync(srcPath, 'utf-8');
+                const destDir = path.dirname(destPath);
+                fs.mkdirSync(destDir, { recursive: true });
+                fs.writeFileSync(destPath, fileContent);
+                // Auto-chmod for executables
+                const ext = path.extname(file.src);
+                if (['.sh', '.py', '.bash', '.bat'].includes(ext)) {
+                    try {
+                        fs.chmodSync(destPath, 0o755);
+                    }
+                    catch (e) {
+                        // chmod not available (Windows)
+                    }
+                }
+                console.log(chalk.green("  ✓ " + (file.dest || file.src)));
+            }
+            else {
+                console.warn(chalk.yellow("  ! " + file.src + " not found, skipping"));
+            }
+        }
+    }
+    // Write .info.md
+    if (!options.dryRun) {
+        const infoContent = `# ${typeName}\n\n${template.description || ''}\n`;
+        fs.writeFileSync(path.join(resolvedDest, '.info.md'), infoContent);
+    }
+    else {
+        console.log(chalk.gray(`  [DRY RUN] Would create .info.md`));
+    }
+    // Use template post_config tasks
+    const allTasks = template.post_config?.filter(t => !t.type || t.type === typeName) || [];
+    if (allTasks.length > 0) {
+        // Determine which tasks to include
+        let selectedTaskNames = [];
+        if (options.skipPostConfig) {
+            // Skip entirely
+            selectedTaskNames = [];
+        }
+        else if (options.dryRun) {
+            // In dry-run, select all (for display)
+            selectedTaskNames = allTasks.map(t => t.command || t.script || '');
+            console.log(chalk.yellow(`\n[DRY RUN] Applicable post-config tasks:`));
+            for (const t of allTasks) {
+                const desc = t.description ? ` (${t.description})` : '';
+                console.log(chalk.gray(`  [template] - ${t.command || t.script}${desc}`));
+            }
+        }
+        else if (options.yes) {
+            // All tasks selected
+            selectedTaskNames = allTasks.map(t => t.command || t.script || '');
+        }
+        else if (allTasks.length === 0) {
+            selectedTaskNames = [];
+        }
+        else {
+            // Checkbox prompt
+            const choices = [];
+            for (const t of allTasks) {
+                const cmd = t.command || t.script || '(no command)';
+                const desc = t.description ? ` (${t.description})` : '';
+                choices.push({
+                    name: `${cmd}${desc}`,
+                    value: cmd,
+                    checked: true
+                });
+            }
+            const response = await inquirer.prompt({
+                type: 'checkbox',
+                name: 'selected',
+                message: 'Select post-config tasks to run:',
+                loop: false,
+                theme: {
+                    icon: {
+                        cursor: chalk.green('[x] ')
+                    }
+                },
+                choices
+            });
+            selectedTaskNames = response.selected || [];
+        }
+        // Write post_config scripts for selected tasks
+        if (selectedTaskNames.length > 0 && !options.dryRun) {
+            let bashContent = '#!/bin/bash\n# Auto-generated post_config script\n\n';
+            let batContent = '@echo off\n:: Auto-generated post_config script\n\n';
+            for (const t of allTasks) {
+                // Determine the actual command/script to use
+                let cmd = '';
+                if (t.command) {
+                    cmd = t.command;
+                }
+                else if (t.script) {
+                    cmd = `./${t.script}`;
+                }
+                // Match against selected names (use command if available, else script)
+                const taskKey = t.command || (t.script ? `./${t.script}` : '');
+                if (selectedTaskNames.includes(taskKey)) {
+                    if (cmd) {
+                        bashContent += `echo "Running: ${t.description || taskKey}"\n${cmd}\n`;
+                        batContent += `echo Running: ${t.description || taskKey}\n${cmd}\n`;
+                    }
+                }
+            }
+            fs.writeFileSync(path.join(resolvedDest, 'post_config.sh'), bashContent);
+            try {
+                fs.chmodSync(path.join(resolvedDest, 'post_config.sh'), 0o755);
+            }
+            catch (e) { }
+            fs.writeFileSync(path.join(resolvedDest, 'post_config.bat'), batContent);
+            // Execute the appropriate script
+            console.log(chalk.cyan("\nExecuting post-config tasks..."));
+            try {
+                const scriptCmd = process.platform === 'win32' ? 'post_config.bat' : './post_config.sh';
+                execSync(scriptCmd, {
+                    cwd: resolvedDest,
+                    stdio: 'inherit'
+                });
+            }
+            catch (e) {
+                console.error(chalk.red("\nError: Some post-config tasks failed. Check the output above."));
+            }
+        }
+    }
+    if (options.dryRun) {
+        console.log(chalk.yellow(`\n[DRY RUN] Project initialization preview complete.`));
+    }
+    else {
+        console.log(chalk.green(`\n✓ Project created successfully.`));
+    }
+}
+function createStructure(dirPath, folders, dryRun = false) {
+    for (const folder of folders) {
+        const fullDirPath = path.join(dirPath, folder.name);
+        if (dryRun) {
+            console.log(chalk.gray(`  [DRY RUN] Would create directory: ${fullDirPath}`));
+        }
+        else {
+            fs.mkdirSync(fullDirPath, { recursive: true });
+        }
+        // Create .info.md if content exists
+        if (folder.info) {
+            const infoPath = path.join(fullDirPath, '.info.md');
+            if (dryRun) {
+                console.log(chalk.gray(`  [DRY RUN] Would create info file: ${infoPath}`));
+            }
+            else {
+                fs.writeFileSync(infoPath, folder.info);
+            }
+        }
+        // Recurse children
+        if (folder.children && folder.children.length > 0) {
+            createStructure(fullDirPath, folder.children, dryRun);
+        }
+    }
+}