190 lines
5.0 KiB
Markdown
190 lines
5.0 KiB
Markdown
# 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. |