📦 projgen-cli

Generate, sync, and maintain your project's file/folder structure from a single structure.txt file — with safety features, templates, and real-time watching.

A powerful CLI tool that lets you define your entire project structure in plain text and keep it perfectly synchronized with your filesystem. Perfect for scaffolding projects, maintaining consistency, and automating project setup.

---

✨ Features

• 🔧 Define structure in plain text - Simple, readable structure.txt format
• 🏗️ Auto-create project trees - Generate entire folder structures instantly
• 🔄 Two-way sync - Keep filesystem and structure.txt in perfect sync
• 🛡️ Safety first - Interactive confirmations, dry-run mode, and force flags
• 🎨 Colored output - Beautiful terminal UI with clear visual feedback
• 📝 Template system - Auto-populate new files with custom templates
• 👀 Watch mode - Real-time synchronization as you edit structure.txt
• 🚫 .projgenignore - Exclude files and folders from scanning
• 💬 Comment support - Add comments to your structure files
• ✅ Strict validation - Catch errors with helpful line-number messages
• 🧪 Fully tested - Comprehensive test suite with Vitest
• 📚 Well documented - Complete JSDoc coverage and examples

---

📥 Installation

Option 1: Use via npx (No install needed)

npx projgen-cli init
npx projgen-cli sync

Option 2: Install globally

npm install -g projgen-cli

Then use anywhere:

projgen init
projgen sync
projgen watch

Option 3: Install locally in project

npm install --save-dev projgen-cli

Add to package.json scripts:

{
  "scripts": {
    "struct:init": "projgen init",
    "struct:sync": "projgen sync",
    "struct:watch": "projgen watch"
  }
}

---

🚀 Quick Start

# 1. Generate structure.txt from your current project
projgen init

# 2. Edit structure.txt to add/remove files and folders

# 3. Preview changes (dry run)
projgen sync --dry-run

# 4. Apply changes
projgen sync

# 5. Or use watch mode for real-time syncing
projgen watch

---

📂 Commands

projgen init

Generate structure.txt from your current directory structure.

projgen init [options]

Options:

• --indent <size> - Indentation style: 2 (default), 4, or tab

Examples:

projgen init                    # Use 2-space indentation
projgen init --indent=4         # Use 4-space indentation
projgen init --indent=tab       # Use tab indentation

---

projgen sync

Synchronize your filesystem with structure.txt.

projgen sync [options]

Options:

• --dry-run - Preview changes without applying them
• --force - Skip confirmation prompts for deletions
• --update-structure - Update structure.txt after sync to reflect actual state
• --indent <size> - Indentation style: 2, 4, or tab
• --log - Write detailed log to .projgen.log

Examples:

projgen sync                          # Interactive sync with confirmations
projgen sync --dry-run                # Preview what will change
projgen sync --force                  # Skip confirmations (use with caution!)
projgen sync --update-structure       # Sync and update structure.txt
projgen sync --indent=4 --log         # Use 4-space indent and log to file

What it does:

• ✅ Creates missing files and folders
• ❌ Deletes files/folders not in structure.txt (with confirmation)
• 🔄 Detects and handles renames
• 📝 Applies templates to new files (if configured)

---

projgen watch

Watch structure.txt for changes and auto-sync in real-time.

projgen watch [options]

Options:

• --indent <size> - Indentation style: 2, 4, or tab

Examples:

projgen watch                   # Start watching with default settings
projgen watch --indent=4        # Watch with 4-space indentation

Features:

• 👀 Monitors structure.txt for changes
• ⚡ Automatically applies additions and deletions
• 🔄 Debounced (waits 500ms after changes)
• 🛑 Graceful shutdown with Ctrl+C

---

📝 structure.txt Format

Basic Syntax

folder src
  folder components
    file Button.js
    file Input.js
  folder utils
    file helpers.js
  file index.js
folder public
  file index.html
file package.json
file README.md

Rules

• Use folder or file followed by the name
• Use 2-space indentation for nesting (or configure with --indent)
• Indentation must be consistent (multiples of indent size)
• No trailing slashes needed

Comments

# This is a comment line

folder src  # This is an inline comment
  file index.js  # Main entry point

• Lines starting with # are ignored
• Inline comments after # are stripped

Indentation Styles

2 spaces (default):

folder src
  file index.js

4 spaces:

folder src
    file index.js

Tabs:

folder src
	file index.js

---

🛡️ Safety Features

Interactive Confirmation

By default, projgen sync will ask for confirmation before deleting files:

About to delete 3 items (2 files, 1 folder). Continue? (y/N)

Dry Run Mode

Preview changes without applying them:

projgen sync --dry-run

Output shows:

• 🟢 What will be created
• 🔴 What will be deleted
• ⚪ What is unchanged

Force Mode

Skip confirmations (use with caution):

projgen sync --force

⚠️ Warning: This will delete files without asking!

Protected Files

These are always ignored:

• .git/
• node_modules/
• .vscode/
• .idea/
• structure.txt
• .projgen.log

---

🎨 Template System

Overview

Automatically populate new files with custom templates based on file extension.

Setup

1. Create a .projgen/templates/ directory in your project
2. Add template files named default.<ext>.template

Example Templates

.projgen/templates/default.js.template:

/**
 * {{filename}}
 * 
 * @file {{name}}
 * @author Your Name
 * @date {{date}}
 */

// Your code here

.projgen/templates/default.md.template:

# {{name}}

Created: {{date}}

## Description

Add your description here.

Template Variables

• {{filename}} - Full filename (e.g., index.js)
• {{name}} - Filename without extension (e.g., index)
• {{date}} - Current date (YYYY-MM-DD)
• {{year}} - Current year
• {{timestamp}} - Full ISO timestamp

Usage

When you run projgen sync, new files will automatically use templates if available:

projgen sync
# Creates src/utils.js with template content

---

🚫 .projgenignore

Overview

Exclude files and folders from scanning when running projgen init.

Format

Create a .projgenignore file in your project root:

# Ignore build artifacts
dist/
build/
*.log

# Ignore IDE files
.vscode/
.idea/

# Ignore test files
*.test.js
__tests__/

Pattern Matching

• Exact match: node_modules
• Wildcard: *.log, *.tmp
• Path match: dist/, build/output/
• Comments: Lines starting with #

Default Ignores

These are always ignored (even without .projgenignore):

• .git
• node_modules
• .vscode
• .idea
• structure.txt
• .projgen.log

---

📊 Project Structure

projgen-cli/
├── src/
│   ├── cli/
│   │   ├── commands/
│   │   │   ├── init.js       # Init command
│   │   │   ├── sync.js       # Sync command
│   │   │   └── watch.js      # Watch command
│   │   └── index.js          # CLI entry point
│   ├── core/
│   │   ├── parser/
│   │   │   └── index.js      # Structure parser
│   │   ├── scanner/
│   │   │   ├── index.js      # Filesystem scanner
│   │   │   └── ignore.js     # .projgenignore handler
│   │   ├── sync/
│   │   │   ├── diff.js       # Diff generator
│   │   │   └── apply.js      # Diff applicator
│   │   ├── templates/
│   │   │   └── index.js      # Template system
│   │   └── watcher/
│   │       └── index.js      # Watch mode
│   └── utils/
│       ├── logger.js         # Colored logging
│       ├── confirm.js        # Interactive prompts
│       └── validator.js      # Validation utilities
├── tests/
│   └── unit/
│       ├── parser.test.js    # Parser tests
│       ├── scanner.test.js   # Scanner tests
│       └── diff.test.js      # Diff tests
├── templates/
│   ├── default.js.template   # Default JS template
│   └── default.md.template   # Default MD template
├── package.json
├── vitest.config.js
└── README.md

---

🧪 Testing

Run the test suite:

npm test                  # Run all tests
npm run test:watch        # Watch mode
npm run test:coverage     # Coverage report
npm run test:ui           # Interactive UI

---

⚠️ Safety Warnings

IMPORTANT: projgen sync will delete files and folders that are not listed in structure.txt.

Best Practices

1. ✅ Always use version control (Git) before syncing
2. ✅ Run --dry-run first to preview changes
3. ✅ Review deletions carefully before confirming
4. ✅ Use .projgenignore to protect important files
5. ✅ Backup your project before major structural changes

What Gets Deleted

• Any file or folder not in structure.txt
• Except items in .projgenignore
• Except default protected items (.git, node_modules, etc.)

---

🤝 Contributing

Contributions are welcome! Here's how to contribute:

Development Setup

# Clone the repository
git clone https://github.com/vaibhavisno-one/ProjGen
cd projgen-cli

# Install dependencies
npm install

# Run tests
npm test

# Link for local development
npm link

Guidelines

• ✅ Write tests for new features
• ✅ Follow existing code style
• ✅ Add JSDoc comments to functions
• ✅ Update README for new features
• ✅ Keep commits atomic and descriptive

Pull Request Process

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests (npm test)
5. Commit changes (git commit -m 'Add amazing feature')
6. Push to branch (git push origin feature/amazing-feature)
7. Open a Pull Request

---

🐛 Troubleshooting

"structure.txt not found"

Run projgen init first to generate the file.

"Invalid indentation" error

Ensure your indentation is consistent:

• Use only spaces OR tabs (not mixed)
• Use multiples of your indent size (2 or 4 spaces)

Files not being ignored

Check your .projgenignore syntax:

• One pattern per line
• No quotes needed
• Use * for wildcards

Templates not working

Ensure templates are in .projgen/templates/ and named default.<ext>.template.

Watch mode not detecting changes

Check that structure.txt exists and is not being ignored by your editor's auto-save settings.

---

📄 License

MIT © Vaibhav kumar

---

🌐 Links

• 📦 npm Package
• 🐙 GitHub Repository
• 🐛 Report Issues
• 💡 Request Features

---

🙏 Acknowledgments

Built with:

• Commander.js - CLI framework
• Chalk - Terminal colors
• Inquirer.js - Interactive prompts
• Chokidar - File watching
• Vitest - Testing framework

---

Made with ❤️ by the ProjGen team