Package Script Writer

Generate customized installation scripts for Umbraco CMS projects

Live Demo · Documentation · Report Bug · Request Feature

🎯 What is Package Script Writer?

Package Script Writer helps Umbraco developers quickly generate installation scripts for new projects. Available as both a web application and a CLI tool, you can choose the interface that fits your workflow!

Web Application - Visit psw.codeshare.co.uk for a visual, browser-based experience

CLI Tool - Install psw as a .NET global tool for terminal-based automation

Simply select your template, choose packages, configure your settings, and get a ready-to-run script!

Perfect for:

🚀 Quick project setup
👥 Team onboarding
📚 Training and tutorials
🔄 Consistent project configurations
🤖 CI/CD automation (CLI)

✨ Features

Template Selection - Choose from Umbraco official templates and community packages
Package Browser - Browse 150+ packages from the Umbraco Marketplace
Version Control - Select specific package versions or use latest
Unattended Install - Pre-configure database and admin credentials
Docker Support - Optional Dockerfile and Docker Compose generation
Shareable URLs - All configuration encoded in the URL for easy sharing
Multiple Formats - Generate multi-line scripts or one-liners
Syntax Highlighting - Clean, readable output with syntax highlighting
Swagger/OpenAPI - Interactive API documentation with Swagger UI

🚀 Quick Start

For Users

Visit psw.codeshare.co.uk
Select your Umbraco template and version
Choose any packages you want to include
Configure your project settings
Click "Generate" and copy your script!

Example Output:

# Ensure we have the version specific Umbraco templates
dotnet new install Umbraco.Templates::14.3.0 --force

# Create solution/project
dotnet new sln --name "MySolution"
dotnet new umbraco --force -n "MyProject" --development-database-type SQLite
dotnet sln add "MyProject"

#Add Packages
dotnet add "MyProject" package Umbraco.Community.BlockPreview --version 1.6.0

dotnet run --project "MyProject"

For Developers

Prerequisites: .NET 10.0 SDK

# Clone the repository
git clone https://github.com/prjseal/Package-Script-Writer.git
cd Package-Script-Writer

# Run the application
dotnet watch run --project ./src/PSW/

# Open browser to https://localhost:5001

That's it! No database setup required - the application is completely stateless.

💻 CLI Tool

Package Script Writer CLI (psw) is a powerful command-line interface that brings the full functionality of PSW to your terminal!

Features

🎨 Beautiful Terminal UI - Built with Spectre.Console for rich interactive experience
🚀 Dual Mode - Interactive prompts OR command-line flags for automation
🎯 Template Selection - Choose from Umbraco official & community templates
📦 Browse 150+ Packages - Search and select from the Umbraco Marketplace
🔄 Resilient - Automatic retry logic with exponential backoff
📝 Verbose Logging - Detailed diagnostics with Serilog
🤖 CI/CD Ready - Perfect for automation and scripts

Quick Install

# Install as a global .NET tool
dotnet tool install --global PackageScriptWriter.Cli --prerelease

# Run from anywhere
psw

Quick Examples

Interactive Mode:

# Launch interactive prompts
psw

CLI Mode:

# Generate default script
psw --default

# Custom script with packages
psw -p "uSync,Diplo.GodMode" -n MyProject

# Full automation with unattended install
psw -p "uSync|17.0.0" -n MyProject -s --solution-name MySolution \
    -u --database-type SQLite --admin-email [email protected] \
    --admin-password "SecurePass123!" --auto-run

Documentation

📚 Full CLI Documentation: src/PackageCliTool/README.md

Includes:

Complete installation guide
All command-line flags and options
Interactive workflow walkthrough
Code architecture and structure
Troubleshooting and logging
Development guide

📖 Documentation

Comprehensive documentation is available in the .github/ directory:

Document	Description
Documentation Index	Main documentation hub with overview
Architecture	System architecture and design patterns
Process Flows	Visual diagrams of all processes
Services	Business logic layer documentation
API Reference	Complete REST API documentation
Frontend	JavaScript and UI architecture
Data Models	All data structures and models
Configuration	Settings and configuration guide
Security	Security measures and best practices
Development Guide	Setup, testing, and contributing
Testing Guide	Integration tests, API testing, and CI/CD

Start here: 📚 Read the Documentation

🛠️ Technology Stack

Framework: ASP.NET Core 10.0
Language: C# 13
Frontend: Razor Pages + Vanilla JavaScript
UI: Bootstrap 5
Caching: In-memory (IMemoryCache)
APIs: NuGet.org, Umbraco Marketplace
Documentation: Swagger/OpenAPI (Swashbuckle)
Testing: xUnit, FluentAssertions, ASP.NET Core Testing
CI/CD: GitHub Actions

Why no database? The application is intentionally stateless for simplicity, security, and easy deployment.

🤝 Contributing

We welcome contributions! Here's how to get started:

Raise an issue - For bugs or features, create an issue first
Discuss - Let's agree on the approach before coding
Fork & branch - Fork the repo and create a feature branch
Code - Make your changes following our code style
Test - Test your changes thoroughly
Submit PR - Create a pull request with clear description

See the Development Guide for detailed contributing instructions.

Development Commands

# Run with hot reload
dotnet watch run --project ./src/PSW/

# Run integration tests
dotnet test

# Build for production
dotnet publish ./src/PSW/PSW.csproj -c Release -o ./publish

# Format code
dotnet format ./src/PSW/PSW.csproj

🧪 Testing

Integration Tests

The project includes comprehensive integration tests that validate all API endpoints using xUnit, HttpClient, and FluentAssertions.

# Run all integration tests
dotnet test

# Run tests with detailed output
dotnet test --verbosity normal

# Run tests with code coverage
dotnet test --collect:"XPlat Code Coverage"

Test Coverage:

✅ Script generation with various configurations
✅ Package version retrieval
✅ Cache clearing functionality
✅ API health checks
✅ Error handling and validation

See Integration Tests README for detailed testing documentation.

Continuous Integration

Every pull request automatically runs all tests via GitHub Actions:

🔄 Automated test execution on all PRs
✅ Build verification across multiple environments
📊 Test result reporting
🚫 PR merge blocked if tests fail

GitHub Actions Workflow: .github/workflows/integration-tests.yml

API Testing

Swagger UI (Interactive Documentation)

The easiest way to explore and test the API is through the built-in Swagger UI:

# Start the application
dotnet watch run --project ./src/PSW/

# Open your browser to:
https://localhost:5001/api/docs

Swagger UI provides:

📖 Interactive API documentation with OpenAPI annotations
🧪 Built-in request testing
📝 Request/response examples
🔍 Schema exploration
📄 Complete API specification

REST Client (VS Code)

The repository includes a Api Request/API Testing.http file for testing with the REST Client VS Code extension.

# Start the application
dotnet watch run --project ./src/PSW/

# Open Api Request/API Testing.http in VS Code
# Click "Send Request" above each endpoint

See API Reference for complete endpoint documentation.

📦 Project Structure

Package-Script-Writer/
├── src/
│   ├── PSW/                        # Main web application
│   │   ├── Components/            # View Components
│   │   ├── Controllers/           # MVC & API Controllers
│   │   ├── Services/              # Business logic
│   │   ├── Models/                # Data models
│   │   ├── Views/                 # Razor views
│   │   └── wwwroot/               # Static files (CSS, JS, images)
│   ├── PackageCliTool/            # CLI tool (.NET Global Tool)
│   │   ├── Configuration/         # API configuration
│   │   ├── Services/              # API client & package selection
│   │   ├── Workflows/             # CLI & interactive modes
│   │   ├── UI/                    # Terminal UI components
│   │   ├── Models/                # DTOs and options
│   │   ├── Logging/               # Serilog setup
│   │   └── Program.cs             # Entry point
│   └── PSW.IntegrationTests/      # Integration test project
│       ├── ScriptGeneratorApiTests.cs
│       └── CustomWebApplicationFactory.cs
├── .github/
│   ├── workflows/                  # GitHub Actions workflows
│   └── *.md                        # Documentation
└── README.md                       # This file

See Architecture for detailed structure.

🔒 Security

The application implements multiple security measures:

✅ Security Headers - X-Frame-Options, CSP, etc.
✅ HTTPS/HSTS - Forced HTTPS connections
✅ Input Validation - Client and server-side
✅ No Data Storage - Stateless, no user data stored
✅ Regular Updates - Dependencies kept current

See Security for complete security documentation.

🐛 Troubleshooting

Common Issues

Port already in use:

# Run on different port
dotnet run --urls "https://localhost:5555"

Certificate errors:

# Trust development certificate
dotnet dev-certs https --trust

Cache issues:

# Clear cache via API
curl https://localhost:5001/api/scriptgeneratorapi/clearcache

See Development Guide for more solutions.

📝 License

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

👨‍💻 Author

Paul Seal

Website: codeshare.co.uk
Twitter: @codeshare
GitHub: @prjseal

🌟 Acknowledgments

Umbraco Community - For the amazing CMS and package ecosystem
Microsoft - For ASP.NET Core and .NET
Contributors - Everyone who has contributed to this project

📊 Project Stats

🔗 Useful Links

Live Site: psw.codeshare.co.uk
Documentation: Technical Documentation
Issues: GitHub Issues
Umbraco: docs.umbraco.com
Marketplace: marketplace.umbraco.com

⭐ If this project helps you, consider giving it a star! ⭐

Made with ❤️ for the Umbraco Community

Name		Name	Last commit message	Last commit date
Latest commit History 395 Commits
.devcontainer		.devcontainer
.github		.github
.vscode		.vscode
API Requests		API Requests
src		src
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md

License

prjseal/Package-Script-Writer

Folders and files

Latest commit

History

Repository files navigation