Open Source Project Generator v2.0

🎉 New in v2.0: Tool-Orchestration Architecture - Leverage industry-standard CLI tools for always up-to-date project generation!

A modern command-line tool that generates production-ready project structures by orchestrating industry-standard CLI tools (create-next-app, go mod init, etc.) with intelligent fallback generation.

🚀 What's New in v2.0?

Tool-Orchestration Architecture

Instead of maintaining templates, v2.0 delegates project generation to official framework tools:

Next.js: Uses create-next-app for latest Next.js projects
Go: Uses go mod init and official Go tooling
Android/iOS: Uses native tooling when available, falls back to minimal generation
Always Current: Get the latest framework versions automatically

Key Improvements

✅ No Template Maintenance: Framework tools handle updates
✅ Better Quality: Official tools generate best-practice code
✅ Enhanced Logging: Comprehensive file logging with timestamps
✅ Automatic Backups: Rollback on failure
✅ Beautiful Output: Colored terminal output with status symbols
✅ Security Scanning: Post-generation security checks
✅ Offline Support: Works without internet after initial setup

📦 Installation

# Using Go
go install github.com/cuesoftinc/open-source-project-generator/cmd/generator@latest

# From source
git clone https://github.com/cuesoftinc/open-source-project-generator
cd open-source-project-generator
make build

# Verify installation
generator --version

🎯 Quick Start

1. Check Your Environment

# Verify required tools are installed
generator check-tools

# Output:
# ✓ npx (v10.2.3) - Available
# ✓ go (v1.21.0) - Available
# ✗ gradle - Not found
#   Install: https://gradle.org/install/

2. Generate Configuration

# Create a configuration template
generator init-config --output project.yaml

3. Customize Configuration

Edit project.yaml:

name: my-awesome-app
description: My full-stack application
output_dir: ./my-awesome-app

components:
  - type: nextjs
    name: web-app
    enabled: true
    config:
      typescript: true
      tailwind: true
      app_router: true

  - type: go-backend
    name: api-server
    enabled: true
    config:
      module: github.com/user/my-awesome-app
      framework: gin

integration:
  generate_docker_compose: true
  generate_scripts: true
  api_endpoints:
    backend: http://localhost:8080

options:
  use_external_tools: true
  create_backup: true
  verbose: false

4. Preview Generation

# Dry-run to see what will be generated
generator generate --config project.yaml --dry-run

5. Generate Project

# Generate your project
generator generate --config project.yaml

# Output:
# ═══════════════════════════════════════════════════════════════════
# Step 1/11: Validating configuration...
# ✓ Configuration validation passed
# Step 2/11: Applying default configuration values...
# ✓ Defaults applied successfully
# ...
# ═══════════════════════════════════════════════════════════════════
# PROJECT GENERATION COMPLETED
# ═══════════════════════════════════════════════════════════════════
# ✓ Project generated successfully in 45.2s
# Project Name: my-awesome-app
# Location: ./my-awesome-app
# Components: 2

🏗️ Generated Project Structure

my-awesome-app/
├── App/                    # Next.js frontend (generated by create-next-app)
│   ├── app/               # App router
│   ├── components/        # React components
│   ├── public/            # Static assets
│   ├── package.json       # Dependencies
│   └── next.config.js     # Next.js configuration
├── CommonServer/          # Go backend (generated by go mod init)
│   ├── cmd/               # Application entry points
│   ├── internal/          # Private application code
│   ├── pkg/               # Public packages
│   ├── go.mod             # Go modules
│   └── main.go            # Main application
├── Mobile/                # Mobile applications
│   ├── android/           # Android project (Gradle/Kotlin)
│   └── ios/               # iOS project (Xcode/Swift)
├── Deploy/                # Infrastructure
│   ├── docker/            # Docker configurations
│   └── k8s/               # Kubernetes manifests
├── .logs/                 # Generation logs
├── docker-compose.yml     # Docker Compose configuration
├── .env                   # Environment variables
├── README.md              # Project documentation
├── TROUBLESHOOTING.md     # Troubleshooting guide
├── build.sh               # Build script
├── dev.sh                 # Development script
└── prod.sh                # Production script

📖 Usage Examples

Full-Stack Web Application

# fullstack.yaml
name: fullstack-app
output_dir: ./fullstack-app

components:
  - type: nextjs
    name: web-app
    enabled: true
    config:
      typescript: true
      tailwind: true

  - type: go-backend
    name: api-server
    enabled: true
    config:
      module: github.com/user/fullstack-app
      framework: gin

integration:
  generate_docker_compose: true
  generate_scripts: true

generator generate --config fullstack.yaml

Mobile Application with Backend

# mobile-app.yaml
name: mobile-app
output_dir: ./mobile-app

components:
  - type: android
    name: mobile-android
    enabled: true
    config:
      package: com.user.mobileapp
      language: kotlin

  - type: ios
    name: mobile-ios
    enabled: true
    config:
      bundle_id: com.user.mobileapp
      language: swift

  - type: go-backend
    name: api-server
    enabled: true
    config:
      module: github.com/user/mobile-app
      framework: gin

integration:
  generate_docker_compose: true
  api_endpoints:
    backend: http://localhost:8080

generator generate --config mobile-app.yaml

Frontend Only

# frontend.yaml
name: my-frontend
output_dir: ./my-frontend

components:
  - type: nextjs
    name: web-app
    enabled: true
    config:
      typescript: true
      tailwind: true
      app_router: true

integration:
  generate_docker_compose: false
  generate_scripts: true

generator generate --config frontend.yaml

🛠️ Commands

Core Commands

# Generate projects
generator generate --config project.yaml    # Generate from configuration
generator generate --config project.yaml --dry-run  # Preview without creating files

# Environment validation
generator check-tools                       # Check tool availability

# Configuration
generator init-config --output project.yaml # Generate configuration template

Command Options

# Generation options
--config <file>          # Configuration file path (required)
--dry-run                # Preview generation without creating files
--verbose                # Enable detailed logging
--no-external-tools      # Force fallback generation
--create-backup          # Create backup before generation
--stream-output          # Stream tool output in real-time
--force-overwrite        # Overwrite existing directories

# Output options
--output <dir>           # Override output directory from config
--log-level <level>      # Set log level (debug, info, warn, error)

🔧 Configuration Reference

Component Types

Type	Description	Bootstrap Tool	Fallback Available
`nextjs`	Next.js frontend	`create-next-app`	No
`go-backend`	Go backend API	`go mod init`	No
`android`	Android mobile app	`gradle`	Yes
`ios`	iOS mobile app	`xcodebuild`	Yes

Component Configuration

Next.js Component:

- type: nextjs
  name: web-app
  enabled: true
  config:
    typescript: true      # Use TypeScript
    tailwind: true        # Include Tailwind CSS
    app_router: true      # Use App Router
    eslint: true          # Include ESLint

Go Backend Component:

- type: go-backend
  name: api-server
  enabled: true
  config:
    module: github.com/user/project  # Go module path
    framework: gin                    # Framework (gin, echo, chi)
    database: postgres                # Database (postgres, mysql, sqlite)

Android Component:

- type: android
  name: mobile-android
  enabled: true
  config:
    package: com.user.app    # Package name
    language: kotlin         # Language (kotlin, java)
    min_sdk: 24             # Minimum SDK version

iOS Component:

- type: ios
  name: mobile-ios
  enabled: true
  config:
    bundle_id: com.user.app  # Bundle identifier
    language: swift          # Language (swift, objc)
    deployment_target: 15.0  # Minimum iOS version

Integration Options

integration:
  generate_docker_compose: true    # Generate docker-compose.yml
  generate_scripts: true           # Generate build/run scripts
  api_endpoints:
    backend: http://localhost:8080 # Backend API endpoint
    auth: http://localhost:8081    # Auth service endpoint

Generation Options

options:
  use_external_tools: true   # Use bootstrap tools (recommended)
  create_backup: true        # Create backup before generation
  verbose: false             # Enable verbose logging
  stream_output: false       # Stream tool output in real-time
  force_overwrite: false     # Overwrite existing directories
  disable_parallel: false    # Disable parallel component generation

🔒 Security Features

Input Sanitization

All user inputs sanitized before processing
Path traversal attack prevention
Project name validation

Security Scanning

Post-generation security scan
Detection of exposed secrets
Identification of insecure configurations
Security report generation

Tool Execution Safety

Whitelisted tools and flags only
Command injection prevention
Timeout protection
Sandboxed execution

Backup and Rollback

Automatic backups before generation
Rollback on failure
Backup restoration
Cleanup of partial generations

📊 Logging and Monitoring

File Logging

All operations are logged to files:

# Log file location
./my-project/.logs/generation-20240101-120000.log

# Log format
[INFO] 2024-01-01 12:00:00 Starting project generation | project=my-app
[DEBUG] 2024-01-01 12:00:01 Sanitizing project name: my-app
[INFO] 2024-01-01 12:00:02 Tool discovery completed | component=nextjs
[INFO] 2024-01-01 12:00:05 Component generated successfully | component=web-app type=nextjs method=bootstrap duration=3.2s

Console Output

Beautiful, colored terminal output:

═══════════════════════════════════════════════════════════════════
PROJECT GENERATION COMPLETED
═══════════════════════════════════════════════════════════════════
✓ Project generated successfully in 45.2s
Project Name: my-awesome-app
Location: ./my-awesome-app
Components: 2

─────────────────────────────────────────────────────
Generated Components
─────────────────────────────────────────────────────
✓ web-app (nextjs) - bootstrap
✓ api-server (go-backend) - bootstrap

─────────────────────────────────────────────────────
Next Steps
─────────────────────────────────────────────────────
  • Navigate to: cd ./my-awesome-app
  • Review the README.md for detailed instructions
  • Run with Docker: docker-compose up
  • Run development mode: ./dev.sh

Log File: ./my-awesome-app/.logs/generation-20240101-120000.log

🚨 Troubleshooting

Tool Not Found

Error: Required tool 'npx' not found

Solution:
# Install Node.js (includes npx)
brew install node  # macOS
sudo apt-get install nodejs npm  # Ubuntu

Generation Failed

Error: Component generation failed: nextjs

Solution:
1. Check the log file for details
2. Verify tool versions: generator check-tools
3. Try with verbose logging: --verbose
4. Use fallback generation: --no-external-tools

Permission Denied

Error: failed to create directory: permission denied

Solution:
# Ensure write permissions
chmod +w ./output-directory
# Or use a different output directory
generator generate --config project.yaml --output ~/projects/my-app

📚 Documentation

Changelog - What's new in v2.0
Migration Guide - Migrating from v1.x
Configuration Guide - Detailed configuration options
CLI Reference - Complete command reference
Troubleshooting - Common issues and solutions
Security Guide - Security best practices

🔄 Migrating from v1.x

If you're upgrading from v1.x, see the Migration Guide for detailed instructions.

Quick migration steps:

Backup existing projects
Install required tools (generator check-tools)
Convert configuration (template → components)
Test with dry-run (--dry-run)
Generate new project

🤝 Contributing

We welcome contributions! Please see our Contributing Guide.

Development Setup

# Clone repository
git clone https://github.com/cuesoftinc/open-source-project-generator
cd open-source-project-generator

# Install dependencies
go mod download

# Build
make build

# Run tests
make test

# Run linter
make lint

# Check for version updates
make check-versions

# Update to latest versions
make update-versions

Version Management

All dependency versions are centrally managed in configs/versions.yaml. This provides a single source of truth for all framework and tool versions used in generated projects.

See configs/VERSIONS.md for details.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

🙏 Acknowledgments

Built with Go
Uses Cobra for CLI
Leverages official framework tools for generation
Community feedback and contributions

Ready to generate your next project? Start with generator check-tools to verify your environment!

FilesExpand file tree

README.md

Latest commit

History