kuma

Kuma is a powerful framework designed to generate project structures for any programming language based on Go templates. It streamlines the process of setting up new projects by automating the creation of directories, files, and base code, ensuring consistency and saving valuable development time.

Table of Contents

• Features
• Installation
• Create Your Own Boilerplates
  • Builders
  • Templates
  • Runs
• Terminal Commands
  • Create a Boilerplate
  • Execute a Run
  • Get Templates from GitHub
    • Official Templates
• Contribution
• License

Features

• Customize your project’s directory and file structures through Go templates.
• GitHub integration to download pre-defined templates from the community or for personal use via private repositories.
• Ability to create custom CLI command workflows through a YAML file using runs.
• Dynamic variable usage to be applied to templates. Variables can be extracted from a local YAML or JSON file or fetched from a public URL. They can also be obtained from user input during the execution of a run.

Installation

Requirements

• Go version 1.23 or higher.
• Git installed and configured on your system.

Step by Step

1. Run the installation command:

   go install github.com/arthurbcp/kuma@latest
   

2. Add the Go bin directory to your PATH (if not already included):

   Add the following line to your shell configuration file (.bashrc, .zshrc, etc.):

   export PATH=$PATH:$(go env GOPATH)/bin
   

   Then, reload your shell or run:

   source ~/.bashrc
   

   Replace .bashrc with your shell configuration file if necessary.

3. Verify if $GOPATH is set correctly:

   Run the following command to display the current value of $GOPATH:

   echo $GOPATH
   

   Expected Results:

   • If $GOPATH is set correctly: The command will return the path to the GOPATH directory, usually something like /home/user/go on Linux or C:Users/user/go on Windows.

   • If $GOPATH is empty or incorrect: You will need to set it by adding the following line to your shell configuration file:

     export GOPATH=$(go env GOPATH)
     

     Then, reload your shell or run:

     source ~/.bashrc
     

     Replace .bashrc with your shell configuration file if necessary.

4. Verify the installation:

   kuma --help
   

   You should see the Kuma CLI help, confirming that the installation was successful.

Create Your Own Boilerplates

For Kuma to work, all framework-related files must be inside the .kuma folder.

The framework uses a parser for Go templates divided into three file types:

Builders

YAML-formatted templates that contain the folder and file structure to be created.

# .kuma/base.yaml

# Global variables to be used in all templates.
global:
  packageName: "{{.data.packageName}}"

# Directory and file structure to be generated
structure:
  # main.go
  main.go:
    # The template that will be used as the basis for creating the main.go file
    template: templates/Main.go

    # Variables that will be used inside the template
    data:
      # msg: Hello, Kuma!
      msg: "{{ .data.msg }}"

Templates

Individual Go templates for the files that will be created.

package main

import (
  "fmt"
)

func main() {
  // fmt.Print("Hello, Kuma!")
  fmt.Println("{{ .data.msg }}")
}

Runs

A YAML file containing a sequence of actions that will be executed when calling a run. It includes logs, terminal commands, HTTP calls, text input, and multiple-choice prompts, along with actions to create folders and files based on builders and templates.

all runs must be located within the .kuma/runs directory

Check the full documentation here.

# Name of the run that will be executed as soon as the repository is obtained via the `kuma get` command
initial:
  # Description of the run
  description: "Initial run to set up the project"

  # Steps that will be executed when the run is called
  steps:
    # Input action
    - input:
        label: "What is the package name of your project?"
        out: packageName # Example: github.com/arthurbcp/kuma-hello-world

    # Another input action
    - input:
        label: "What message would you like to print?"
        out: msg # Example: Hello, Kuma!

    # Log message
    - log: "Creating structure for {{.data.packageName}}" # Example: Creating structure for github.com/arthurbcp/kuma-hello-world

    # Create the project structure using the base.yaml builder
    - create:
        from: base.yaml

    # Success log
    - log: "Base structure created successfully!"

    # Initialize the Go module
    - cmd: go mod init {{.data.packageName}} # Example: go mod init github.com/arthurbcp/kuma-hello-world

    # Install dependencies
    - cmd: go mod tidy

    # Run the main.go file
    - cmd: go run main.go # Example: Hello, Kuma!

Additional Notes

• This project uses sprout as a dependency, which contains hundreds of extremely useful functions for working with Go templates. In addition to our official functions, further enhancing your experience with our framework.

  Sproute: Official Docs

  Kuma functions: Read me  

Terminal Commands

Create a Boilerplate

The create command is used to create a boilerplate based on the builders and templates inside the .kuma folder and a JSON or YAML file containing the variables to replace in the templates.

kuma create --variables=swagger.json --project=. --from=base.yaml

Flags:

• --variables, -v: Path or URL to the variables file.
• --project, -p: Path to the project where the boilerplate will be created.
• --from, -f: Path to the YAML file with the structure and templates.

Execute a Run

The exec command is used to start the process of a run.

kuma exec --run=initial

Flags:

• --run, -r: Name of the run to be executed.

Get Templates from GitHub

Fetch templates and runs from a GitHub repository.

You can get templates from any repository using the command:

kuma get --repo=arthurbcp/typescript-rest-openapi-services

Or use one of our official templates with:

kuma get --template=typescript-rest-openapi-services

Note: If the .kuma/runs.yaml file contains a run named initial, this run will be executed automatically after the get command is executed.

Flags:

• --repo, -r: Name of the GitHub repository.
• --template, -t: Name of the official template.

Official Templates

• Hello World: A simple Hello World in Go.
• OpenAPI 2.0 TypeScript Services: Create a TypeScript library with typed services for all endpoints described in an Open API 2.0 file.

Contribution

Contributions are welcome! Feel free to open issues or submit pull requests to improve Kuma.

1. Fork the repository.

2. Create a branch for your feature:

   git checkout -b feature/my-new-feature
   

3. Commit your changes:

   git commit -m "Add new feature"
   

4. Push to the branch:

   git push origin feature/my-new-feature
   

5. Open a Pull Request.

License

This project is licensed under the MIT license. See the LICENSE file for more details.