@pixpilot/scaffoldfy

A flexible and powerful task automation utility for project setup, cleanup, and configuration.

Features

• 🔄 13 Task Types - update-json, template, create, regex-replace, replace-in-file, delete, rename, move, copy, append, mkdir, git-init, exec
• 🧩 Template Inheritance - Extend base templates for code reuse
• 🔍 Dry-Run Mode with Diff - Preview exact changes before applying
• 🔌 Plugin System - Create custom task types and lifecycle hooks
• 💬 Interactive Prompts - Collect user input with input, select, confirm, number, and password prompts
• � Variables - Define reusable values from static or executable sources without user interaction
• �📦 JSON/TypeScript Config - Define tasks in JSON or TypeScript files
• 🔗 Task Dependencies - Ensure tasks run in the correct order
• ✅ Type-Safe - Full TypeScript support with JSON schema validation
• 🎯 Template Variables - Use {{variable}} syntax for dynamic configuration
• 📝 Handlebars Support - Advanced templating with conditionals, loops, and helpers
• ⚡ CLI & Programmatic - Use as a command-line tool or import as a library

Installation

pnpm add @pixpilot/scaffoldfy

Quick Start

CLI Usage

# Basic usage with default task file
scaffoldfy

# With custom tasks file
scaffoldfy --tasks-file ./my-tasks.json

# Preview changes (dry run)
scaffoldfy --dry-run

Or run without installing using npx:

# Basic usage with default task file
npx @pixpilot/scaffoldfy

# With custom tasks file
npx @pixpilot/scaffoldfy --tasks-file ./my-tasks.json

# Preview changes (dry run)
npx @pixpilot/scaffoldfy --dry-run

CLI Options

Programmatic API

import { runWithTasks } from '@pixpilot/scaffoldfy';

await runWithTasks(tasks, {
  dryRun: false,
  force: false,
  tasksFilePath: './my-tasks.json',
});

Task Types

13 built-in task types for common operations:

📖 Complete Task Types Reference →

Interactive Prompts

Collect user input at the root level - prompts are collected once before tasks run and available to all tasks:

{
  "prompts": [
    {
      "id": "projectName",
      "type": "input",
      "message": "What is your project name?",
      "required": true
    },
    {
      "id": "useTypeScript",
      "type": "confirm",
      "message": "Use TypeScript?",
      "default": true
    }
  ],
  "tasks": [
    {
      "id": "setup",
      "name": "Setup Project",
      "type": "update-json",
      "config": {
        "file": "package.json",
        "updates": {
          "name": "{{projectName}}"
        }
      }
    }
  ]
}

Supported prompt types: input, password, number, select, confirm

Root-level only: Prompts are defined at the root level, collected once upfront, and available to all tasks

💬 Full Prompts Guide → | 📋 Quick Reference →

Variables

Define reusable values without user interaction - automatically resolved from static values or executable commands:

{
  "variables": [
    {
      "id": "currentYear",
      "value": {
        "type": "exec",
        "value": "node -e \"console.log(new Date().getFullYear())\""
      }
    },
    {
      "id": "gitUserName",
      "value": {
        "type": "exec",
        "value": "git config user.name"
      }
    },
    {
      "id": "defaultLicense",
      "value": "MIT"
    }
  ],
  "tasks": [
    {
      "id": "update-license",
      "type": "template",
      "config": {
        "file": "LICENSE",
        "template": "Copyright {{currentYear}} {{gitUserName}}\n\nLicense: {{defaultLicense}}"
      }
    }
  ]
}

Use in tasks: Reference variables using {{variable}} syntax: {{currentYear}}, {{gitUserName}}, {{defaultLicense}}

Variable types: Static values, executable commands (with auto-parsing), or conditional expressions

📌 Complete Variables Guide →

Handlebars Templates

Create powerful file templates with Handlebars support. Files with .hbs extension automatically use Handlebars templating:

{
  "id": "readme-from-template",
  "name": "Generate README",
  "type": "template",
  "config": {
    "file": "README.md",
    "templateFile": "templates/readme.hbs"
  }
}

Automatic detection: Any template file ending in .hbs uses Handlebars. Other files use simple {{variable}} interpolation.

Template file (templates/readme.hbs):

#
{{projectName}}

{{#if description}}
  >
  {{description}}
{{else}}
  > A modern TypeScript project
{{/if}}

## Features

{{#each features}}
  -
  {{this}}
{{/each}}

{{#if author}}
  ## Author

  {{author}}
{{/if}}

Key features:

• File-based only: Handlebars is only supported for external template files (.hbs extension)
• Automatic detection: No configuration needed - just use .hbs files
• Conditionals: {{#if}}, {{#unless}}, {{else}}
• Loops: {{#each}}, {{#with}}
• Comments: {{!-- This won't appear in output --}}

📝 Complete Handlebars Guide →

Template Inheritance

Extend base templates to promote code reuse:

{
  "extends": "./base-template.json",
  "tasks": [
    {
      "id": "custom-task",
      "name": "Custom Task",
      "description": "Project-specific setup",
      "required": true,
      "enabled": true,
      "type": "exec",
      "config": { "command": "echo 'Custom setup'" }
    }
  ]
}

You can extend multiple templates, override tasks by ID, and merge dependencies automatically.

🧬 Complete Inheritance Guide →

Dry-Run Mode with Diff Preview

Preview exactly what will change before applying:

scaffoldfy --tasks-file ./tasks.json --dry-run

See color-coded diffs for all file modifications, deletions, and additions.

🔍 Dry-Run Documentation →

Plugin System

Create custom task types for specialized operations:

import { createPlugin, registerPlugin } from '@pixpilot/scaffoldfy';

const myPlugin = createPlugin(
  'my-plugin',
  'custom-task',
  async (task, config, options) => {
    // Your custom logic here
  },
);

registerPlugin(myPlugin);

🔌 Complete Plugin Guide →

Task Dependencies

Control execution order:

{
  "tasks": [
    { "id": "clean", "type": "delete", "config": { "paths": ["dist"] } },
    {
      "id": "build",
      "dependencies": ["clean"],
      "type": "exec",
      "config": { "command": "pnpm build" }
    }
  ]
}

Example Configuration

Complete Example with Prompts and Variables

{
  "prompts": [
    {
      "id": "projectName",
      "type": "input",
      "message": "What is your project name?",
      "required": true
    },
    {
      "id": "author",
      "type": "input",
      "message": "Who is the author?",
      "default": {
        "type": "exec",
        "value": "git config user.name"
      }
    },
    {
      "id": "useTypeScript",
      "type": "confirm",
      "message": "Use TypeScript?",
      "default": true
    }
  ],
  "variables": [
    {
      "id": "currentYear",
      "value": {
        "type": "exec",
        "value": "node -e \"console.log(new Date().getFullYear())\""
      }
    },
    {
      "id": "license",
      "value": "MIT"
    }
  ],
  "tasks": [
    {
      "id": "update-package",
      "name": "Update package.json",
      "description": "Set project metadata",
      "type": "update-json",
      "config": {
        "file": "package.json",
        "updates": {
          "name": "{{projectName}}",
          "author": "{{author}}",
          "license": "{{license}}"
        }
      }
    },
    {
      "id": "create-readme",
      "name": "Create README",
      "description": "Generate README file",
      "type": "template",
      "config": {
        "file": "README.md",
        "template": "# {{projectName}}\n\nAuthor: {{author}}\nCopyright {{currentYear}}"
      }
    }
  ]
}

Simple Example

{
  "prompts": [
    {
      "id": "projectName",
      "type": "input",
      "message": "Project name?",
      "required": true
    }
  ],
  "tasks": [
    {
      "id": "update-package",
      "name": "Update package.json",
      "type": "update-json",
      "config": {
        "file": "package.json",
        "updates": {
          "name": "{{projectName}}"
        }
      }
    }
  ]
}

📁 More Examples →

Documentation

📚 Complete Documentation - Comprehensive guides and references

Quick Links

• Getting Started - Installation, CLI usage, and examples
• Task Types Reference - All 13 built-in task types
• Interactive Prompts - Collect user input
• Variables - Reusable values without user interaction
• Advanced Features - Conditional execution, global prompts, Handlebars
• Template Inheritance - Extend and compose templates
• Plugin System - Create custom task types
• Dry-Run Mode - Preview changes safely

Resources

• JSON Schema - For IDE autocomplete and validation
• Example Files - Sample task configurations

JSON Schema Support

Enable autocomplete and validation in your IDE:

{
  "$schema": "node_modules/@pixpilot/scaffoldfy/schema/tasks.schema.json",
  "tasks": []
}

Contributing

Contributions are welcome! Please check out the Contributing Guide for guidelines.

Development

# Install dependencies
pnpm install

# Run tests
pnpm test

# Run tests in watch mode
pnpm test --watch

# Build
pnpm build

# Type check
pnpm typecheck

License

MIT