scaffoldforge/README.md

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.

Features

• Parse GitHub issue descriptions, checklists, and comments
• Generate project structures from templates
• Create starter files with TODO comments
• Support multiple languages (Python, JavaScript, Go, Rust)
• Custom template system
• Preview mode before generating
• Interactive mode with prompts

Installation

pip install scaffoldforge

Or from source:

git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/scaffoldforge.git
cd scaffoldforge
pip install -e .

Quick Start

1. Set up your GitHub Personal Access Token:

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

Usage

Basic Usage

Generate a project from a GitHub issue URL:

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:

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

Preview what will be generated:

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

Specify custom output directory:

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

Interactive mode:

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

List available templates:

scaffoldforge list-templates --language python

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

Custom Templates

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

SCAFFOLD_TEMPLATE_DIR=./custom_templates scaffoldforge generate <issue_url>

Configuration

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:

cp .env.example .env

How It Works

1. Issue Parsing: Fetches the GitHub issue and parses title, description, checklist items, and labels
2. Language Detection: Automatically detects programming language from labels or content
3. Template Selection: Selects appropriate templates based on language
4. Context Generation: Creates template context with issue data
5. File Generation: Renders templates and writes files
6. Documentation: Generates README.md and .gitignore

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.