@garyr/pt-cli 0.32.1 → 0.33.0

package/doc/usage.md

@@ -22,26 +22,24 @@ 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:
+`pt learn` supports learning templates directly from a remote Git repository or tarball archive by passing an `http://` or `https://` URL. **Security is enforced**: only downloads from `trustedSources` (configured in `~/.pt/config.yaml`) are allowed by default. Untrusted sources trigger a warning and require explicit confirmation.
 
 ```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`.
 
+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. **Security Verification:** Downloads are restricted to trusted sources (configured in `~/.pt/config.yaml`). Untrusted sources trigger a warning and require explicit confirmation.
+3. **Download & Extraction:** The tool downloads the archive into a secure temporary folder and extracts it. File size is validated (max 50MB).
+4. **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.
+5. **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. 
+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.
 
 - **Detection Range:** Root files and 1st-level subfolder files (e.g., `README.md`, `.makerc`, `DOC/closedown.md`).
 - **Registration:** Any detected variables are automatically added to the template's configuration with default prompts (e.g., `Enter variable_name:`).
@@ -141,7 +139,12 @@ The JSON template config file is the recommended way to make a template director
   "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": "project_name",
+      "prompt": "Project name:",
+      "default": "my-app",
+      "required": true
+    },
     { "name": "author", "prompt": "Author name:", "default": "" }
   ],
   "folders": [
@@ -149,16 +152,18 @@ The JSON template config file is the recommended way to make a template director
     { "name": "tests", "children": [] }
   ],
   "copy_files": [
-    { "src": "package.json", "dest": "package.json", "substitute_variables": true },
+    {
+      "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" }
-  ]
+  "post_copy": [{ "src": "bin/start.sh", "dest": "bin/start.sh" }]
 }
 ```
 
@@ -189,30 +194,39 @@ pt init ./new-project --file .pt-template.json --yes
 For a more portable, text-based approach, you can export and import templates as JSON strings or files.
 
 #### Exporting a Template to JSON
+
 To export an existing template from your configuration as JSON:
+
 ```bash
 pt config <template_name> --json > my_template.json
 ```
 
 #### Importing a Template from JSON
+
 To add a template from a JSON file:
+
 ```bash
 pt add <template_name> --file my_template.json
 ```
 
 Or from a JSON string:
+
 ```bash
 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
 pt config --json
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@garyr/pt-cli",
-  "version": "0.32.1",
+  "version": "0.33.0",
   "description": "Project Template CLI - Learn structures and initialize projects",
   "main": "dist/index.js",
   "bin": {
@@ -14,9 +14,9 @@
     "test": "node --import tsx --test tests/**/*.test.ts",
     "test:sequential": "node --import tsx --test tests/config.test.ts && node --import tsx --test tests/init.test.ts && node --import tsx --test tests/learn.test.ts && node --import tsx --test tests/substitute.test.ts && node --import tsx --test tests/config-utils.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",
-    "build:windows": "bun build ./src/index.ts --compile --target=bun-windows-x64 --outfile ../BUILD/pt-cli/pt-win.exe",
+    "build:linux": "bun build ./src/index.ts --compile --minify --target=bun-linux-x64   --outfile ../BUILD/pt-cli/pt-linux",
+    "build:macos": "bun build ./src/index.ts --compile --minify --target=bun-darwin-x64  --outfile ../BUILD/pt-cli/pt-macos",
+    "build:windows": "bun build ./src/index.ts --compile --minify --target=bun-windows-x64 --outfile ../BUILD/pt-cli/pt-win.exe",
     "build:all": "npm run build:linux && npm run build:macos && npm run build:windows"
   },
   "license": "MIT",

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

@@ -79,17 +79,25 @@ 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
-5. Or scaffold directly without registering: `pt init ./new-project --file .pt-template.json --yes`
+The complete portable template workflow, perfect for sharing:
+
+1. **Create template:** `pt init <template> <dest> --yes --skip-post-config` — creates structure without auto-executing post-config tasks (e.g., `git init`)
+2. **Export config:** `pt config <template> --json > <dest>/.pt-template.json` — exports portable JSON config, required to include variables
+3. **Share directory/JSON:** Share the directory or JSON file
+4. **Recipient:** `pt learn <path> --name <template> --yes` — imports the template
+5. **Or scaffold directly:** `pt init ./new-project --file .pt-template.json --yes`
 
 ### JSON Output for Sharing
 
 You can output a template as JSON for sharing without saving it: `pt learn <source_path> --json`
 
+### Important Notes
+
+- **Never use manual `mkdir`/`cp` steps** — `pt init` already scaffolds directory structures, and manual file copying bypasses template registration
+- **`--skip-post-config` flag** prevents premature task execution during template creation
+- **JSON export captures all template metadata**, variables, and post-config tasks for maximum portability
+- The workflow ensures portability by bundling metadata and files together, allowing recipients to import via `pt learn` without manual directory manipulation
+
 ## 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:
@@ -128,6 +136,56 @@ Global variables are defined in `~/.pt/config.yaml` under `variables`. They act
 - Atomic saves, backups, and safe initialization logic prevent data loss.
 - Platform-specific post-config scripts (`.sh`/`.bat`) are executed automatically based on the OS.
 
+## Security Configuration
+
+### Security Policy Settings
+
+Security settings are configured in `~/.pt/config.yaml` under the `security` key:
+
+```yaml
+security:
+  securityLevel: "warn"  # "warn" (default) or "strict"
+  trustedSources:
+    - "github.com/garyritchie"
+    - "git.lyonritchie.com"
+    - "github.com/lyonritchie"
+  maxExecutionTime: 30000  # 30 seconds per command
+  maxCommandsPerRun: 50    # rate limit per init session
+  enableAuditLogging: true # write events to security-audit.log
+```
+
+### Security Levels
+
+- **`warn`** (default): Warning-based approach with cancellation prompts
+- **`strict`**: More conservative defaults, enabled by default for new installations
+
+### Trusted Sources
+
+When downloading templates from remote URLs, `pt-cli` verifies the source against the `trustedSources` list. Untrusted sources trigger a warning and require explicit user confirmation before proceeding.
+
+### Command Security
+
+- **Absolute blocks**: Commands like `sudo`, `rm -rf`, `dd` are always blocked
+- **Dangerous commands**: Commands like `curl`, `python`, `chmod` trigger warnings
+- **Rate limiting**: 50 commands per run prevents runaway execution
+- **Execution timeout**: 30 seconds per command prevents hung processes
+
+### Audit Logging
+
+All security events are logged to `~/.pt/security-audit.log` for monitoring and troubleshooting.
+
+## Security Testing
+
+Security features can be tested by:
+
+1. **Testing command blocks**: Try running templates with dangerous commands like `sudo rm -rf` or `dd`
+2. **Testing remote downloads**: Use untrusted URLs to verify source verification
+3. **Testing rate limiting**: Execute more than 50 commands in a single init session
+4. **Testing timeouts**: Run commands that hang to verify timeout behavior
+5. **Reviewing audit logs**: Check `~/.pt/security-audit.log` for security events
+
+For more details, see the [Security Guide](security.md).
+
 ## CLI Reference
 
 | Command | Description |

package/src/config.ts

@@ -3,6 +3,7 @@ import fs from 'fs';
 import path from 'path';
 import os from 'os';
 import chalk from 'chalk';
+import { SecurityPolicy } from './safety.js';
 
 export function getHomeDir(): string {
   return path.join(os.homedir(), '.pt');
@@ -65,6 +66,7 @@ export interface PtConfig {
   ignore?: string[];  // top-level folder ignore patterns for pt learn
   default_post_config?: PostConfigTask[];  // default post-config tasks applied to all projects
   variables?: TemplateVariable[];         // global variables for substitution
+  security?: SecurityPolicy;  // security policy configuration
 }
 
 export function ensureConfigDir() {
@@ -221,6 +223,25 @@ export function getDefaultPostConfig(config: PtConfig): PostConfigTask[] {
   }));
 }
 
+/**
+ * Get security policy from config or use defaults
+ */
+export function getSecurityPolicy(config: PtConfig): SecurityPolicy {
+  const defaultPolicy: SecurityPolicy = {
+    maxExecutionTime: 30000, // 30 seconds
+    enableAuditLogging: true,
+    trustedSources: [
+      'github.com/garyritchie',
+      'gitea.lyonritchie.com/garyritchie',
+      'github.com/lyonritchie',
+    ],
+    maxCommandsPerRun: 50,
+    securityLevel: 'warn',
+  };
+
+  return config.security || defaultPolicy;
+}
+
 // Default exclusions for template scanning
 export const DEFAULT_EXCLUDES = [
   '.git',

package/src/postconfig.ts

@@ -1,9 +1,19 @@
 import fs from 'fs';
 import path from 'path';
+import os from 'os';
 import { execSync } from 'child_process';
 import chalk from 'chalk';
 import inquirer from 'inquirer';
 import { PostConfigTask } from './config.js';
+import {
+  isBlockedCommand,
+  isDangerousCommand,
+  executeWithTimeout,
+  logSecurityEvent,
+  canExecute,
+  showDangerousCommandWarning,
+  getSecurityPolicy,
+} from './safety.js';
 
 export interface PostConfigOptions {
   skipPostConfig?: boolean;
@@ -22,6 +32,16 @@ export async function runPostConfig(
 ): Promise<void> {
   if (options.skipPostConfig) return;
 
+  // Load security policy
+  const configPath = path.join(process.env.HOME || os.homedir(), '.pt', 'config.yaml');
+  const securityPolicy = getSecurityPolicy(configPath);
+
+  // Check rate limiting
+  if (!canExecute('init', securityPolicy.maxCommandsPerRun)) {
+    console.log(chalk.yellow('⚠️  Rate limit reached: max commands per run exceeded'));
+    return;
+  }
+
   // 1. Filter tasks by type
   const applicableTasks = tasks.filter(t => !t.type || t.type === projectType);
 
@@ -54,18 +74,59 @@ export async function runPostConfig(
     const progress = `[${i + 1}/${applicableTasks.length}]`;
 
     if (task.command) {
+      // SECURITY CHECK 1: Blocklist check (NEVER allow these)
+      if (isBlockedCommand(task.command)) {
+        console.log(chalk.red(`${progress} ⚠️  BLOCKED: ${task.command}`));
+        logSecurityEvent('command_blocked', task.command, projectType, 'blocked');
+        continue;
+      }
+
+      // SECURITY CHECK 2: Dangerous command warning (but allow execution)
+      if (isDangerousCommand(task.command)) {
+        console.log(chalk.yellow(`${progress} ⚠️  WARNING: This command may be dangerous: ${task.command}`));
+        console.log(chalk.yellow(`   Press CTRL+C to cancel, or wait 5s to continue...`));
+        
+        // Wait for user to cancel or timeout
+        const allowContinue = await showDangerousCommandWarning(task.command, 5);
+        if (!allowContinue) {
+          console.log(chalk.yellow(`${progress} ⊘ Command cancelled by user`));
+          logSecurityEvent('command_blocked', task.command, projectType, 'blocked');
+          continue;
+        }
+      }
+
+      // SECURITY CHECK 3: Rate limiting
+      if (!canExecute(task.command, securityPolicy.maxCommandsPerRun)) {
+        console.log(chalk.red(`${progress} ⚠️  Rate limited: too many commands executed`));
+        continue;
+      }
+
       if (options.dryRun) {
         console.log(chalk.gray(`  [DRY RUN] Would run: ${task.command}`));
       } else {
         try {
           console.log(chalk.yellow(`\n${progress} Running: ${task.command}`));
-          execSync(task.command, {
-            cwd: destPath,
-            stdio: 'inherit'
-          });
-          console.log(chalk.green('  ✓ Command completed successfully'));
+          
+          // SECURITY CHECK 4: Execution timeout
+          const result = await executeWithTimeout(
+            task.command,
+            destPath,
+            securityPolicy.maxExecutionTime
+          );
+
+          if (result.timedOut) {
+            console.log(chalk.red(`  ✗ Command timed out after ${securityPolicy.maxExecutionTime / 1000}s`));
+            logSecurityEvent('command_timed_out', task.command, projectType, 'timedout');
+          } else if (result.success) {
+            console.log(chalk.green('  ✓ Command completed successfully'));
+            logSecurityEvent('command_executed', task.command, projectType, 'success');
+          } else {
+            console.log(chalk.red(`  ✗ Command failed: ${result.stderr}`));
+            logSecurityEvent('command_executed', task.command, projectType, 'failed');
+          }
         } catch (err) {
           console.log(chalk.red('  ✗ Command failed'));
+          logSecurityEvent('command_executed', task.command, projectType, 'failed');
         }
       }
     }

package/src/remote.ts

@@ -5,8 +5,36 @@ import os from 'os';
 import { Readable } from 'stream';
 import { finished } from 'stream/promises';
 import { extract } from 'tar'; // You'll need: npm install tar
+import chalk from 'chalk';
+import { isTrustedSource, logSecurityEvent, getSecurityPolicy } from './safety.js';
+import { loadConfig } from './config.js';
 
 export async function downloadAndExtract(url: string): Promise<string> {
+    // Load security policy
+    const configPath = path.join(process.env.HOME || os.homedir(), '.pt', 'config.yaml');
+    const config = loadConfig();
+    const securityPolicy = config.security || {
+        trustedSources: ['github.com/garyritchie', 'gitea.lyonritchie.com/garyritchie', 'github.com/lyonritchie'],
+    };
+
+    // SECURITY CHECK: Verify source is trusted
+    if (!isTrustedSource(url, securityPolicy.trustedSources)) {
+        console.log(chalk.yellow(`⚠️  Warning: Template from untrusted source: ${url}`));
+        console.log(chalk.yellow('   Only use templates from trusted sources'));
+        
+        const inquirer = (await import('inquirer')).default;
+        const response = await inquirer.prompt({
+            type: 'confirm',
+            name: 'proceed',
+            message: chalk.red('Continue anyway?'),
+            default: false
+        });
+        
+        if (!response.proceed) {
+            throw new Error('Download cancelled by user due to untrusted source');
+        }
+    }
+
     const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pt-template-'));
     let downloadUrl = url;
 
@@ -27,10 +55,21 @@ export async function downloadAndExtract(url: string): Promise<string> {
     const fileStream = fs.createWriteStream(dest);
     await finished(Readable.fromWeb(response.body as any).pipe(fileStream));
 
+    // SECURITY: Validate downloaded file before extraction
+    const stats = fs.statSync(dest);
+    if (stats.size > 50 * 1024 * 1024) { // 50MB limit
+        throw new Error('Downloaded template is too large (>50MB)');
+    }
+
     // Extract tarball
     await extract({ file: dest, cwd: tempDir });
     
     // Find the actual content folder (archives usually wrap content in a folder)
     const dirs = fs.readdirSync(tempDir).filter(f => fs.statSync(path.join(tempDir, f)).isDirectory());
-    return path.join(tempDir, dirs[0]); 
+    const extractedPath = path.join(tempDir, dirs[0]);
+    
+    // SECURITY: Log successful download
+    logSecurityEvent('template_loaded', downloadUrl, 'remote', 'success');
+    
+    return extractedPath;
 }