# ScaffoldForge

ScaffoldForge is a CLI tool that parses GitHub issues and automatically generates project scaffolds with starter code, file structures, and TODO comments. Developers can point it at a repo and issue, and it creates a development-ready starting point with placeholders for implementation.

## Installation

```bash
pip install scaffoldforge
```

Or from source:

```bash
git clone https://github.com/yourusername/scaffoldforge.git
cd scaffoldforge
pip install -e .
```

## Quick Start

1. Set up your GitHub Personal Access Token:
   ```bash
export GITHUB_TOKEN=your_github_token_here
```

2. Generate a project from a GitHub issue:
   ```bash
scaffoldforge generate https://github.com/owner/repo/issues/123
```

## Configuration

ScaffoldForge can be configured using environment variables or a configuration file.

### Environment Variables

| Variable | Description | Required |
|----------|-------------|----------|
| `GITHUB_TOKEN` | GitHub Personal Access Token for API access | Yes |
| `SCAFFOLD_TEMPLATE_DIR` | Default template directory path | No |
| `SCAFFOLD_OUTPUT_DIR` | Default output directory | No |

### Configuration File

Copy `.env.example` to `.env` and fill in your values:

```bash
cp .env.example .env
```

Edit `.env` to add your GitHub token.

## Usage

### Basic Usage

Generate a project from a GitHub issue URL:

```bash
scaffoldforge generate https://github.com/owner/repo/issues/123
```

### Options

| Option | Short | Description |
|--------|-------|-------------|
| `--language` | `-l` | Programming language (python, javascript, go, rust) |
| `--template` | `-t` | Template to use |
| `--output` | `-o` | Output directory for generated project |
| `--preview` | `-p` | Preview the structure without writing files |
| `--interactive` | `-i` | Interactive mode with prompts |
| `--verbose` | `-v` | Enable verbose output |

### Examples

Generate a Python project:

```bash
scaffoldforge generate https://github.com/owner/repo/issues/123 -l python
```

Preview what will be generated:

```bash
scaffoldforge generate https://github.com/owner/repo/issues/123 --preview
```

Specify custom output directory:

```bash
scaffoldforge generate https://github.com/owner/repo/issues/123 -o ./my-project
```

Interactive mode:

```bash
scaffoldforge generate https://github.com/owner/repo/issues/123 --interactive
```

### List Available Templates

```bash
scaffoldforge list-templates --language python
```

## Custom Templates

You can create custom templates for ScaffoldForge. Place your templates in a directory and set the `SCAFFOLD_TEMPLATE_DIR` environment variable.

### Template Structure

```
custom_templates/
├── python/
│   ├── default/
│   │   ├── main.py.j2
│   │   └── utils.py.j2
│   └── cli/
│       └── main.py.j2
└── javascript/
    └── default/
        └── index.js.j2
```

### Template Variables

Templates can use the following variables:

| Variable | Description |
|----------|-------------|
| `project_name` | Sanitized project name |
| `project_name_kebab` | kebab-case project name |
| `project_name_snake` | snake_case project name |
| `project_name_pascal` | PascalCase project name |
| `issue_number` | GitHub issue number |
| `issue_title` | GitHub issue title |
| `issue_url` | GitHub issue URL |
| `repository` | Repository identifier (owner/repo) |
| `author` | Issue author |
| `created_date` | Issue creation date |
| `todo_items` | List of incomplete checklist items |
| `completed_items` | List of completed checklist items |
| `requirements` | List of requirements |
| `acceptance_criteria` | List of acceptance criteria |

## Supported Languages

- **Python** - Generates `main.py`, `utils.py`, `models.py`, `pyproject.toml`
- **JavaScript** - Generates `index.js`, `utils.js`, `package.json`
- **Go** - Generates `main.go`, `utils.go`, `go.mod`
- **Rust** - Generates `main.rs`, `lib.rs`, `Cargo.toml`

## How It Works

1. **Issue Parsing**: ScaffoldForge fetches the GitHub issue and parses:
   - Title and description
   - Checklist items (converted to TODO comments)
   - Labels (used for language detection)
   - Requirements sections
   - Suggested file/directory paths

2. **Template Selection**: Based on the detected or specified language, appropriate templates are selected.

3. **Context Generation**: A template context is created with issue data and project name.

4. **File Generation**: Templates are rendered with the context and files are written to the output directory.

5. **Documentation**: A `README.md` and `.gitignore` are automatically generated.

## Error Handling

ScaffoldForge handles common errors gracefully:

- **GitHub API rate limit**: Suggests using a token
- **Invalid URL**: Validates and provides clear error messages
- **Template errors**: Shows syntax errors in templates
- **Permission errors**: Validates output paths

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Run tests: `pytest tests/ -v`
6. Submit a pull request

## License

MIT License - see LICENSE file for details.