Catesta

Branch	Windows - PowerShell	Windows - pwsh	Linux	MacOS
master
Enhancements

Synopsis

Catesta is a PowerShell module project generator. It uses templates to rapidly scaffold test and build integration for a variety of CI/CD platforms.

Description

Catesta enables you to quickly scaffold a PowerShell module or Vault extension project with proper formatting, test + build automation, CI/CD integration, with just one line of code.

• Catesta scaffolds an empty PowerShell/Vault extension module project that adheres to PowerShell community guidelines.
• It generates a few Pester tests to get you started.
• It makes a build file that analyzes your code for best practices and styling, runs Pester tests, creates PowerShell help, and combines your functions together to build your project for publication.
• It will create resources you need to trigger CI/CD builds for your module.
• When you commit your code to your chosen repository, the build(s) will run, and you can view the results.

Why

Simplify the process of structuring your module so that you can focus on building a great PowerShell module instead of the layout and build requirements.

Features

• Catesta can build two types of module projects:
  1. PowerShell module layout following PowerShell community practices
  2. SecretManagement Vault extension module layout following PowerShell community practices
• [Selection] Required CI/CD integration files generated:
  • AWS
  • GitHub Actions
  • Azure Pipelines
  • AppVeyor
• [Selection] Build types for easy cross-platform testing
  • Windows PowerShell
  • Windows pwsh
  • Linux
  • MacOS
• InvokeBuild tasks for validation / analysis / test / build automation
  • PSScriptAnalyzer code checks
    • [Optional] Code Style Enforcement (Stroustrup, OTBS, Allman)
  • Pester Tests
    • Will run Unit / Infrastructure Tests if available
    • Generates Code Coverage Report
    • Coverage Gutters support
  • [Optional] Create Help using platyPS
    • Markdown-based help
    • External XML help file generation
  • Build and artifact creation
• [Optional] VSCode editor files
• [Optional] Helpful repository files
  • .gitignore
  • Project LICENSE (MIT / APACHE / GNU / ISC)
  • Changelog
  • GitHub community files:
    • Code of Conduct
    • Contributing guidelines
    • Templates
      • Issue Bug Report
      • Issue Feature Request
      • Pull Request

Installation

# Install Catesta from the PowerShell Gallery
Install-Module -Name Catesta -Repository PSGallery -Scope CurrentUser

Quick start

PowerShell Module

# Scaffolds a PowerShell module project for integration with AWS CodeBuild.
New-PowerShellProject -CICDChoice 'AWS' -DestinationPath c:\path\AWSProject

# Scaffolds a PowerShell module project for integration with GitHub Actions Workflows.
New-PowerShellProject -CICDChoice 'GitHubActions' -DestinationPath c:\path\GitHubActions

# Scaffolds a PowerShell module project for integration with Azure DevOps Pipelines.
New-PowerShellProject -CICDChoice 'Azure' -DestinationPath c:\path\AzurePipeline

# Scaffolds a PowerShell module project for integration with AppVeyor Projects.
New-PowerShellProject -CICDChoice 'AppVeyor' -DestinationPath c:\path\AppVeyor

# Scaffolds a basic PowerShell module project with no additional extras. You just get a basic PowerShell module construct.
New-PowerShellProject -CICDChoice 'ModuleOnly' -DestinationPath c:\path\ModuleOnly

SecretManagement Vault Extension Module

# Scaffolds a PowerShell SecretManagement vault module project for integration with AWS CodeBuild.
New-VaultProject -CICDChoice 'AWS' -DestinationPath c:\path\AWSProject

# Scaffolds a PowerShell SecretManagement vault module project for integration with GitHub Actions Workflows.
New-VaultProject -CICDChoice 'GitHubActions' -DestinationPath c:\path\GitHubActions

# Scaffolds a PowerShell SecretManagement vault module project for integration with Azure DevOps Pipelines.
New-VaultProject -CICDChoice 'Azure' -DestinationPath c:\path\AzurePipeline

# Scaffolds a PowerShell SecretManagement vault module project for integration with AppVeyor Projects.
New-VaultProject -CICDChoice 'AppVeyor' -DestinationPath c:\path\AppVeyor

# Scaffolds a basic PowerShell SecretManagement vault module project with no additional extras. You just get a basic module construct.
New-VaultProject -CICDChoice 'ModuleOnly' -DestinationPath c:\path\ModuleOnly

Getting Started

1. Use Catesta to scaffold your PowerShell/Vault project with your desired CI/CD platform and builds.
2. Write your module (the hardest part)
   • All build testing can be done locally by navigating to src and running Invoke-Build
   • If using VSCode as your primary editor you can use tasks to perform various local actions
     • Examples:
       • Press Ctrl+P, then type 'task .' - Runs complete build (all tasks)
       • Press Ctrl+P, then type 'task Test' - Invokes all Pester Unit Tests
       • Press Ctrl+P, then type 'task Analyze' - Invokes Script Analyzer checks
       • Press Ctrl+P, then type 'task DevCC' - Generates generate xml file to graphically display code coverage in VSCode using Coverage Gutters
3. Add any module dependencies to your CI/CD bootstrap file:
   • AWS: install_modules.ps1
   • GitHub Actions: actions_bootstrap.ps1
   • Azure: actions_bootstrap.ps1
   • AppVeyor: actions_bootstrap.ps1
4. Commit your project to desired repository that is integrated with your CI/CD platform. This will trigger the build actions.
5. Evaluate results of your builds and display your README badges proudly!

Additional Catesta documentation that covers the process of CI/CD integration in depth:

• Catesta - AWS Doc
• Catesta - GitHub Actions Doc
• Catesta - Azure Pipelines Doc
• Catesta - GitHub AppVeyor Doc

FAQ

Catesta - FAQ

Author

Jake Morrison - https://techthoughts.info/

Contributors

• Andrew Pearce
• Dave Kaylor

Notes

Additional Catesta documentation that covers PowerShell Vault Extension module projects more in depth:

• Catesta-Vault-Extension

Changelog

Reference the Changelog