gentf 0.1.4
Generate file structures from text tree files and scaffold React/Next.js projects
License: MIT
Requires Python: >=3.8
Keywords: file-structure, scaffolding, react, nextjs, cli, generator, template, project-generator

# gentf

Generate file structures from text tree files. A simple CLI tool that creates directory structures and scaffolds framework projects from plain text definitions.

## What is gentf?

gentf reads a text file describing a directory structure and creates that structure on your filesystem. It can also scaffold React or Next.js projects and merge your custom file structure into them.

Instead of manually creating dozens of folders and files, write a simple text tree and let gentf do the work.

## Installation

```bash
pip install gentf
```

## Quick Start

### Basic Usage

Create a text file describing your structure:

```txt
my-project/
├── src/
│   ├── components/
│   │   └── Button.tsx
│   └── App.tsx
├── public/
│   └── favicon.ico
└── package.json
```

Then generate it:

```bash
gentf my-project.txt
```

This creates the entire structure in your current directory. Use `-o` to specify a different output location:

```bash
gentf my-project.txt -o ./output
```

### Framework Scaffolding

gentf can scaffold React or Next.js projects and then apply your custom structure to them.

**React with Vite:**
```bash
gentf project.txt --type react --variant vite
```

**React with Create React App:**
```bash
gentf project.txt --type react --variant cra
```

**Next.js (App Router):**
```bash
gentf project.txt --type next --variant default
```

**Next.js with TypeScript:**
```bash
gentf project.txt --type next --variant ts
```

**Next.js with Turbopack:**
```bash
gentf project.txt --type next --variant turbopack
```

**Next.js Pages Router:**
```bash
gentf project.txt --type next --variant pages
```

When you use framework scaffolding, gentf will:
1. Create the framework project (React or Next.js)
2. Apply your custom file structure from the tree file
3. Merge everything together intelligently

## Tree File Format

You can write your structure using box-drawing characters:

```txt
project-root/
├── src/
│   ├── components/
│   │   └── Button.tsx
│   └── pages/
│       └── Home.tsx
├── public/
│   └── favicon.ico
└── package.json
```

Or use simple indentation:

```txt
project-root/
    src/
        components/
            Button.tsx
        pages/
            Home.tsx
    public/
        favicon.ico
    package.json
```

Comments (lines starting with `#`) are automatically ignored, so you can add notes:

```txt
project/
├── src/
│   ├── components/    # Reusable UI components
│   └── utils/         # Helper functions
└── tests/             # Test files
```

## How It Works

**Project Name**: The project name is automatically derived from your tree file name. If your file is `myapp.txt`, the project will be named `myapp`.

**Smart Unwrapping**: If your tree file has a top-level directory matching the project name, gentf automatically unwraps it to avoid creating nested structures. For example, if your tree file is `myapp.txt` and contains `myapp/` at the top level, the contents go directly into the project root instead of creating `myapp/myapp/`.

**Intelligent Merging**: When scaffolding frameworks, your custom files are merged with the scaffolded project files. Existing files are preserved, and new files from your tree are added.

## Examples

### Simple Structure Generation

Create a `structure.txt` file:

```txt
my-app/
├── src/
│   └── index.js
├── public/
│   └── index.html
└── README.md
```

Generate it:

```bash
gentf structure.txt
```

### React Project with Custom Structure

Create `myapp.txt`:

```txt
myapp/
├── src/
│   ├── components/
│   │   └── Header.tsx
│   └── hooks/
│       └── useAuth.ts
└── public/
    └── logo.svg
```

Scaffold and apply:

```bash
gentf myapp.txt --type react --variant vite -o ./projects
```

This creates a React + Vite project in `./projects/myapp/` with your custom structure merged in.

### Next.js TypeScript Project

```bash
gentf myapp.txt --type next --variant ts
```

Creates a Next.js TypeScript project with your custom file structure.

## Requirements

- Python 3.8 or higher
- Node.js and npm (required for framework scaffolding)

## Getting Help

View all available options and detailed help:

```bash
gentf --help
```

## Development

For local development:

```bash
# Clone the repository
git clone https://github.com/yourusername/gentf
cd gentf

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in editable mode
pip install -e .

# Run tests
pytest tests/
```

See [DEVELOPMENT.md](DEVELOPMENT.md) for more details.

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Contributing

Contributions are welcome. Please feel free to submit a Pull Request.