@pixpilot/scaffoldfy 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 pixpilot
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,431 @@
+# @pixpilot/scaffoldfy
+
+A flexible and powerful template initialization utility for automating project setup, cleanup, and configuration tasks.
+
+## Features
+
+- 🔄 **9 Task Types** - update-json, template, regex-replace, replace-in-file, delete, conditional-delete, rename, 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
+- 📦 **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
+
+```sh
+pnpm add @pixpilot/scaffoldfy
+```
+
+## Quick Start
+
+### CLI Usage
+
+```sh
+# Basic usage with default task file
+scaffoldfy
+
+# With custom tasks file
+scaffoldfy --tasks-file ./my-tasks.json
+
+# TypeScript tasks file
+scaffoldfy --tasks-ts ./my-tasks.ts
+
+# Preview changes (dry run)
+scaffoldfy --dry-run
+
+# Force re-initialization
+scaffoldfy --force
+```
+
+### CLI Options
+
+| Option                | Description                                                   |
+| --------------------- | ------------------------------------------------------------- |
+| `--tasks-file <path>` | Path to JSON task file (default: `./template-tasks.json`)     |
+| `--tasks-ts <path>`   | Path to TypeScript task file (default: `./template-tasks.ts`) |
+| `--dry-run`           | Preview changes without applying them                         |
+| `--force`             | Force re-initialization                                       |
+| `--keep-tasks-file`   | Keep task file after completion (default: remove)             |
+| `-h, --help`          | Show help message                                             |
+| `-v, --version`       | Show version                                                  |
+
+### Programmatic API
+
+```typescript
+import { runWithTasks } from '@pixpilot/scaffoldfy';
+
+await runWithTasks(tasks, {
+  dryRun: false,
+  force: false,
+  keepTasksFile: true,
+  tasksFilePath: './my-tasks.json',
+});
+```
+
+## Core Concepts
+
+### Task Types
+
+9 built-in task types for common operations:
+
+| Type                 | Purpose                                            |
+| -------------------- | -------------------------------------------------- |
+| `update-json`        | Update JSON files (supports nested properties)     |
+| `template`           | Create files from templates (simple or Handlebars) |
+| `regex-replace`      | Find and replace with regex                        |
+| `replace-in-file`    | Simple find and replace                            |
+| `delete`             | Remove files/directories                           |
+| `conditional-delete` | Remove based on conditions                         |
+| `rename`             | Rename or move files                               |
+| `git-init`           | Initialize git repository                          |
+| `exec`               | Execute shell commands                             |
+
+📖 **[Complete Task Types Reference →](docs/TASK_TYPES.md)**
+
+### Interactive Prompts
+
+Collect custom user input directly in your task definitions:
+
+```json
+{
+  "id": "setup",
+  "prompts": [
+    {
+      "id": "projectName",
+      "type": "input",
+      "message": "What is your project name?",
+      "required": true,
+      "global": true
+    },
+    {
+      "id": "useTypeScript",
+      "type": "confirm",
+      "message": "Use TypeScript?",
+      "default": true
+    }
+  ],
+  "config": {
+    "file": "package.json",
+    "updates": {
+      "name": "{{projectName}}"
+    }
+  }
+}
+```
+
+**Supported prompt types:** `input`, `password`, `number`, `select`, `confirm`
+
+**Global prompts:** Mark prompts with `"global": true` to share values across all tasks
+
+💬 **[Full Prompts Guide →](docs/PROMPTS.md)** | 📋 **[Quick Reference →](docs/PROMPTS_QUICK_REFERENCE.md)**
+
+### Template Variables
+
+Use `{{variable}}` syntax anywhere in your task configs:
+
+```json
+{
+  "updates": {
+    "name": "{{repoName}}",
+    "author": "{{author}}",
+    "repository": "{{repoUrl}}"
+  }
+}
+```
+
+**Built-in variables:** `repoName`, `repoOwner`, `repoUrl`, `author`, `baseRepoUrl`, `orgName`
+
+**Custom variables:** Any prompt values you define (e.g., `{{projectName}}`, `{{port}}`)
+
+### Handlebars Templates
+
+Create powerful file templates with Handlebars support. Files with `.hbs` extension automatically use Handlebars templating:
+
+```json
+{
+  "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`):
+
+```handlebars
+#
+{{repoName}}
+
+{{#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 →](docs/HANDLEBARS_TEMPLATES.md)**
+
+### Template Inheritance
+
+Extend base templates to promote code reuse:
+
+```json
+{
+  "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 →](docs/TEMPLATE_INHERITANCE.md)**
+
+### Dry-Run Mode with Diff Preview
+
+Preview exactly what will change before applying:
+
+```bash
+scaffoldfy --tasks-file ./tasks.json --dry-run
+```
+
+See color-coded diffs for all file modifications, deletions, and additions.
+
+🔍 **[Dry-Run Documentation →](docs/DRY_RUN.md)**
+
+### Plugin System
+
+Create custom task types for specialized operations:
+
+```typescript
+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 →](docs/PLUGINS.md)**
+
+### Task Dependencies
+
+Control execution order:
+
+```json
+{
+  "tasks": [
+    { "id": "clean", "type": "delete", "config": { "paths": ["dist"] } },
+    {
+      "id": "build",
+      "dependencies": ["clean"],
+      "type": "exec",
+      "config": { "command": "pnpm build" }
+    }
+  ]
+}
+```
+
+## Example Configuration
+
+### Simple Example
+
+```json
+{
+  "tasks": [
+    {
+      "id": "update-package",
+      "name": "Update package.json",
+      "description": "Update repository information",
+      "required": true,
+      "enabled": true,
+      "type": "update-json",
+      "config": {
+        "file": "package.json",
+        "updates": {
+          "name": "{{repoName}}",
+          "author": "{{author}}"
+        }
+      }
+    }
+  ]
+}
+```
+
+### With Prompts
+
+```json
+{
+  "tasks": [
+    {
+      "id": "setup-project",
+      "name": "Setup Project",
+      "description": "Configure project settings",
+      "required": true,
+      "enabled": true,
+      "type": "update-json",
+      "prompts": [
+        {
+          "id": "projectName",
+          "type": "input",
+          "message": "Project name?",
+          "required": true
+        },
+        {
+          "id": "includeTests",
+          "type": "confirm",
+          "message": "Include tests?",
+          "default": true
+        }
+      ],
+      "config": {
+        "file": "package.json",
+        "updates": {
+          "name": "{{projectName}}",
+          "scripts": {
+            "test": "{{includeTests ? 'vitest' : 'echo \"No tests\"'}}"
+          }
+        }
+      }
+    }
+  ]
+}
+```
+
+📁 **[More Examples →](examples/)**
+
+## Documentation
+
+📚 **[Complete Documentation](../../docs/README.md)** - Start here for comprehensive guides and references
+
+### Quick Links
+
+- **[Getting Started](../../docs/GETTING_STARTED.md)** - Installation, CLI usage, and examples
+- **[Task Types Reference](../../docs/TASK_TYPES.md)** - All 9 built-in task types
+- **[Interactive Prompts](../../docs/PROMPTS.md)** - Collect user input
+- **[Advanced Features](../../docs/FEATURES.md)** - Conditional execution, global prompts, Handlebars
+- **[Template Inheritance](../../docs/TEMPLATE_INHERITANCE.md)** - Extend and compose templates
+- **[Plugin System](../../docs/PLUGINS.md)** - Create custom task types
+- **[Dry-Run Mode](../../docs/DRY_RUN.md)** - Preview changes safely
+
+### Resources
+
+- **[JSON Schema](schema/tasks.schema.json)** - For IDE autocomplete and validation
+- **[Example Files](examples/)** - Sample task configurations
+
+### 📁 Project Structure
+
+```
+scaffoldfy (monorepo)/
+├── docs/                          # Complete documentation
+│   ├── README.md                  # Documentation index
+│   ├── GETTING_STARTED.md         # Getting started guide
+│   ├── FEATURES.md                # Advanced features
+│   ├── TASK_TYPES.md              # Task types reference
+│   ├── PROMPTS.md                 # Prompts guide
+│   ├── PROMPTS_QUICK_REFERENCE.md # Quick reference
+│   ├── TEMPLATE_INHERITANCE.md    # Inheritance guide
+│   ├── HANDLEBARS_TEMPLATES.md    # Handlebars guide
+│   ├── PLUGINS.md                 # Plugin system
+│   ├── DRY_RUN.md                 # Dry-run mode
+│   └── EXECUTABLE_DEFAULTS_REFERENCE.md
+└── packages/
+    └── scaffoldfy/                # Main package
+        ├── src/
+        │   ├── cli.ts             # CLI entry point
+        │   ├── types.ts           # TypeScript definitions
+        │   ├── config.ts          # Configuration
+        │   ├── prompts.ts         # Prompt handling
+        │   ├── task-executors.ts  # Task execution
+        │   ├── task-resolver.ts   # Dependency resolution
+        │   └── utils.ts           # Utilities
+        ├── schema/
+        │   └── tasks.schema.json  # JSON schema
+        ├── examples/              # Example configurations
+        └── test/                  # Test files
+```
+
+## JSON Schema Support
+
+Enable autocomplete and validation in your IDE:
+
+```json
+{
+  "$schema": "node_modules/@pixpilot/scaffoldfy/schema/tasks.schema.json",
+  "tasks": []
+}
+```
+
+## Contributing
+
+Contributions are welcome! Please check out the [Contributing Guide](../../CONTRIBUTING.md) for guidelines.
+
+### Development
+
+```sh
+# 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

package/dist/cli.cjs

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+const e=require(`./src-eu70b3xC.cjs`);let t=require(`node:fs`);t=e.Y(t);let n=require(`node:path`);n=e.Y(n);let r=require(`node:process`);r=e.Y(r);let i=require(`commander`);i=e.Y(i);const a=1,o=new i.Command,s=n.default.join(__dirname,`..`,`package.json`);let c=`0.0.0`;try{c=JSON.parse(t.default.readFileSync(s,`utf-8`)).version??`0.0.0`}catch{}o.name(`scaffoldfy`).description(`Initialize and configure project templates with customizable tasks`).version(c),o.option(`--dry-run`,`Run in dry mode without making any changes`).option(`--force`,`Force re-initialization even if already initialized`).option(`--keep-tasks-file`,`Keep the tasks file after successful initialization (default: remove)`,!1).option(`--tasks-file <path>`,`Path to JSON file containing task definitions`,`./template-tasks.json`).option(`--tasks-ts <path>`,`Path to TypeScript file exporting tasks`,`./template-tasks.ts`).action(async i=>{try{let a=[],o;if(i.tasksTs!=null&&i.tasksTs!==``){let s=n.default.resolve(r.default.cwd(),i.tasksTs);if(t.default.existsSync(s)){e.G(`Loading tasks from TypeScript file: ${i.tasksTs}`,`info`),o=s;try{let t=await import(s);a=t.default??t.tasks??[],(!Array.isArray(a)||a.length===0)&&(e.G(`⚠️  No tasks found in TypeScript file or invalid format`,`warn`),e.G(`Expected default export or named export "tasks" with TaskDefinition[]`,`info`))}catch(t){e.G(`Failed to load TypeScript tasks file: ${i.tasksTs}`,`error`),t instanceof Error&&e.G(`  Error: ${t.message}`,`error`),r.default.exit(1)}}}if(a.length===0&&i.tasksFile!=null&&i.tasksFile!==``){let s=n.default.resolve(r.default.cwd(),i.tasksFile);if(t.default.existsSync(s)){o=s;try{a=await e.a(s),Array.isArray(a)||(e.G(`❌ Invalid tasks file format`,`error`),e.G(`Expected JSON with { "tasks": [...] } structure`,`info`),r.default.exit(1))}catch(t){e.G(`Failed to load JSON tasks file: ${i.tasksFile}`,`error`),t instanceof Error&&e.G(`  Error: ${t.message}`,`error`),r.default.exit(1)}}else e.G(`Tasks file not found: ${i.tasksFile}`,`warn`)}a.length===0&&(e.G(`❌ No tasks defined`,`error`),console.log(``),e.G(`Please provide tasks using one of these methods:`,`info`),e.G(`  1. Create a template-tasks.json file in the current directory`,`info`),e.G(`  2. Create a template-tasks.ts file in the current directory`,`info`),e.G(`  3. Use --tasks-file option to specify a different JSON file`,`info`),e.G(`  4. Use --tasks-ts option to specify a different TypeScript file`,`info`),console.log(``),e.G(`Example JSON structure:`,`info`),console.log(JSON.stringify({tasks:[{id:`update-package`,name:`Update package.json`,description:`Update package.json with repository information`,required:!0,enabled:!0,type:`update-json`,prompts:[{id:`projectName`,type:`input`,message:`What is your project name?`,default:`my-project`,required:!0},{id:`includeTests`,type:`confirm`,message:`Include test files?`,default:!0}],config:{file:`package.json`,updates:{name:`{{projectName}}`,author:`{{author}}`}}}]},null,2)),console.log(``),r.default.exit(1)),console.log(``),e.G(`Loaded ${a.length} task(s)`,`success`),console.log(``),await e.n(a,{dryRun:i.dryRun,force:i.force,keepTasksFile:i.keepTasksFile,tasksFilePath:o})}catch(t){if(e.G(`❌ CLI execution failed`,`error`),t instanceof Error){e.G(`Error: ${t.message}`,`error`);let n=r.default.env.DEBUG;n!=null&&n!==``&&console.error(t.stack)}else console.error(t);r.default.exit(1)}}),o.parse(r.default.argv);

package/dist/cli.d.cts

@@ -0,0 +1 @@
+export { };

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export { };

package/dist/cli.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import{G as e,a as t,n}from"./src-Cn-rEwSc.js";import r from"node:path";import{fileURLToPath as i}from"node:url";import a from"node:fs";import o from"node:process";import{Command as s}from"commander";const c=()=>i(import.meta.url),l=(()=>r.dirname(c()))(),u=new s,d=r.join(l,`..`,`package.json`);let f=`0.0.0`;try{f=JSON.parse(a.readFileSync(d,`utf-8`)).version??`0.0.0`}catch{}u.name(`scaffoldfy`).description(`Initialize and configure project templates with customizable tasks`).version(f),u.option(`--dry-run`,`Run in dry mode without making any changes`).option(`--force`,`Force re-initialization even if already initialized`).option(`--keep-tasks-file`,`Keep the tasks file after successful initialization (default: remove)`,!1).option(`--tasks-file <path>`,`Path to JSON file containing task definitions`,`./template-tasks.json`).option(`--tasks-ts <path>`,`Path to TypeScript file exporting tasks`,`./template-tasks.ts`).action(async i=>{try{let s=[],c;if(i.tasksTs!=null&&i.tasksTs!==``){let t=r.resolve(o.cwd(),i.tasksTs);if(a.existsSync(t)){e(`Loading tasks from TypeScript file: ${i.tasksTs}`,`info`),c=t;try{let n=await import(t);s=n.default??n.tasks??[],(!Array.isArray(s)||s.length===0)&&(e(`⚠️  No tasks found in TypeScript file or invalid format`,`warn`),e(`Expected default export or named export "tasks" with TaskDefinition[]`,`info`))}catch(t){e(`Failed to load TypeScript tasks file: ${i.tasksTs}`,`error`),t instanceof Error&&e(`  Error: ${t.message}`,`error`),o.exit(1)}}}if(s.length===0&&i.tasksFile!=null&&i.tasksFile!==``){let n=r.resolve(o.cwd(),i.tasksFile);if(a.existsSync(n)){c=n;try{s=await t(n),Array.isArray(s)||(e(`❌ Invalid tasks file format`,`error`),e(`Expected JSON with { "tasks": [...] } structure`,`info`),o.exit(1))}catch(t){e(`Failed to load JSON tasks file: ${i.tasksFile}`,`error`),t instanceof Error&&e(`  Error: ${t.message}`,`error`),o.exit(1)}}else e(`Tasks file not found: ${i.tasksFile}`,`warn`)}s.length===0&&(e(`❌ No tasks defined`,`error`),console.log(``),e(`Please provide tasks using one of these methods:`,`info`),e(`  1. Create a template-tasks.json file in the current directory`,`info`),e(`  2. Create a template-tasks.ts file in the current directory`,`info`),e(`  3. Use --tasks-file option to specify a different JSON file`,`info`),e(`  4. Use --tasks-ts option to specify a different TypeScript file`,`info`),console.log(``),e(`Example JSON structure:`,`info`),console.log(JSON.stringify({tasks:[{id:`update-package`,name:`Update package.json`,description:`Update package.json with repository information`,required:!0,enabled:!0,type:`update-json`,prompts:[{id:`projectName`,type:`input`,message:`What is your project name?`,default:`my-project`,required:!0},{id:`includeTests`,type:`confirm`,message:`Include test files?`,default:!0}],config:{file:`package.json`,updates:{name:`{{projectName}}`,author:`{{author}}`}}}]},null,2)),console.log(``),o.exit(1)),console.log(``),e(`Loaded ${s.length} task(s)`,`success`),console.log(``),await n(s,{dryRun:i.dryRun,force:i.force,keepTasksFile:i.keepTasksFile,tasksFilePath:c})}catch(t){if(e(`❌ CLI execution failed`,`error`),t instanceof Error){e(`Error: ${t.message}`,`error`);let n=o.env.DEBUG;n!=null&&n!==``&&console.error(t.stack)}else console.error(t);o.exit(1)}}),u.parse(o.argv);export{};

package/dist/index.cjs

@@ -0,0 +1 @@
+const e=require(`./src-eu70b3xC.cjs`);exports.callHook=e._,exports.clearPlugins=e.v,exports.clearTemplateCache=e.r,exports.collectConfig=e.B,exports.collectPrompts=e.p,exports.createPlugin=e.y,exports.displayTasksDiff=e.A,exports.evaluateCondition=e.H,exports.executePluginTask=e.b,exports.executeTask=e.l,exports.getDeleteDiff=e.j,exports.getExecDiff=e.M,exports.getGitInitDiff=e.N,exports.getGitRepoInfo=e.U,exports.getPlugin=e.x,exports.getPluginForTaskType=e.S,exports.getPluginTaskDiff=e.C,exports.getRegexReplaceDiff=e.P,exports.getRenameDiff=e.F,exports.getReplaceInFileDiff=e.I,exports.getTaskDiff=e.L,exports.getTemplateDiff=e.R,exports.getUpdateJsonDiff=e.z,exports.interpolateTemplate=e.W,exports.isPluginTaskType=e.w,exports.listPlugins=e.T,exports.loadAndMergeTemplate=e.i,exports.loadInitializationState=e.d,exports.loadTasksWithInheritance=e.a,exports.loadTemplate=e.o,exports.log=e.G,exports.main=e.t,exports.mergeTemplates=e.s,exports.prompt=e.K,exports.promptYesNo=e.q,exports.registerHooks=e.E,exports.registerPlugin=e.D,exports.resolveAllDefaultValues=e.m,exports.resolveDefaultValue=e.h,exports.runTask=e.u,exports.runWithTasks=e.n,exports.saveInitializationState=e.f,exports.setNestedProperty=e.J,exports.topologicalSort=e.c,exports.unregisterPlugin=e.O,exports.validateConfig=e.V,exports.validatePluginTask=e.k,exports.validatePrompts=e.g;