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.

Installation

pip install scaffoldforge

Or from source:

git clone https://github.com/yourusername/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

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:

cp .env.example .env

Edit .env to add your GitHub token.

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

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.