craft

README

craft

---

• How to use ?
• Commands
  • Generate
• Craft file
  • VSCode association and schema
• Plugins
  • Generic
  • Golang
  • Helm
  • License
  • Nodejs
  • OpenAPI v2

How to use ?

go install github.com/kilianpaquier/craft/cmd/craft@latest

Commands

Craft stands here to generate a similar project layout for all your projects. 
Multiple coding languages are supported and even helm chart can be generated. 
For more information please consult each command specificities.

Usage:
  craft [command]

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  generate    Generate the project layout
  help        Help about any command
  init        Initialize the project layout
  version     Shows current craft version

Flags:
  -h, --help               help for craft
  -l, --log-level string   set logging level

Use "craft [command] --help" for more information about a command.

Generate

Generate the project layout

Usage:
  craft generate [flags]

Flags:
  -f, --force strings   force regenerating a list of templates (.gitlab-ci.yml, sonar.properties, Dockerfile, etc.)
      --force-all       force regenerating all templates (.gitlab-ci.yml, sonar.properties, Dockerfile, etc.)
  -h, --help            help for generate

Global Flags:
  -l, --log-level string   set logging level

Craft file

Craft project generation is based on root's .craft file, it can contain the following configurations:

# project's description (optional)
# used in various places like helm Chart.yml description
# Dockerfile description label
# api.yml description
description: some useful description

# project's maintainers (at least one must be provided)
# the first maintainer will be referenced in various places like in goreleaser configuration
# Dockerfile maintainer / authors label
# sonar.properties organization and project key prefix
# helm values.yml for images owner (e.g ghcr.io/maintainer/app_name)
# api.yml main contact
# all maintainers will be referenced in dependabot assignees and reviewers
# helm Chart.yml maintainers
maintainers:
  - name: maintainer
    email: maintainer@example.com
    url: maintainer.example.com

# project's license (optional)
# providing it will download the appropriate license
# used in various places like api.yml license
# goreleaser executables license
# github release workflow license addition to releases 
license: agpl-3.0 | apache-2.0 | bsd-2-clause | bsd-3-clause | bsl-1.0 | cc0-1.0 | epl-2.0 | gpl-2.0 | gpl-3.0 | lgpl-2.1 | mit | mpl-2.0 | unlicense

# project's CI (optional)
# providing it will create the appropriate ci files (.gitlab-ci.yml, .github/workflows/...)
ci:
  # ci name - self-explaining what each value will generate - (required when ci section is given)
  name: github | gitlab
  # ci options, providing one or multiple options with tune the ci generation (optional)
  options:
    - codecov
    - codeql
    - dependabot
    - pages
    - renovate
    - sonar

# platform override in case of gitlab on premise, bitbucket on premise, etc.
# by default, an on premise gitlab will be matched if the host contains "gitlab"
# by default, an on premise bitbucket will be matched if the host contains "bitbucket" or "stash"
# when not overridden, the platform is matched based on "git config --get remote.origin.url" on the returned host (github.com, gitlab.com, ...)
platform: bitbucket | gitea | github | gitlab

# specific property to override package manager used for generation on nodejs projects.
# by default, it's "pnpm" because it's faster than npm and more near (in terms of culture) npm than yarn would be.
package_manager: pnpm | npm | yarn

# project's api configuration
# providing it will create an api layer with golang
api:
  # project's api openapi version
  # not provided or provided as 'v2', the api layer will be generated with the help of go-swagger
  # provided as 'v3', the api layer will not be generated (not yet implemented)
  openapi_version: v2 | v3

docker:
  # specific docker registry to push images on (optional, default is none - docker.io)
  # used in various places like helm values.yml images registry
  # github release workflow to push images
  registry: ghcr.io
  # specific exposed port (optional, default is 3000)
  # used in various places like helm values.yml service port
  # Dockerfile exposed port
  port: 3000

# whether to generate an helm chart or not (optional)
no_chart: true | false

# whether to use goreleaser or not, it's only useful on golang based projects (optional)
no_goreleaser: true | false

# whether to generate a Makefile with useful commands (optional)
# this option is automatically disabled when working with nodejs plugin
no_makefile: true | false

VSCode association and schema

When working on vscode, feel free to use craft's schema to help use setup your project:

{
    "files.associations": {
        ".craft": "yaml"
    },
    "yaml.schemas": {
        "https://raw.githubusercontent.com/kilianpaquier/craft/main/.schemas/craft.schema.json": [
            "**/.craft", 
            "!**/chart/.craft"
        ]
    }
}

Plugins

Craft generation is based on plugins. Each plugin detects from .craft configuration and project's files if it needs to generate its part (or not).

Multiple plugins are implemented, and generates various files (please consult the examples folder for more information):

Generic

When no primary plugins is detected (golang or nodejs), then this plugin is automatically used for generation.

It doesn't generate much, just some CI files (in case CI option is provided) for versioning (semantic release), a README.md and makefiles (to easily generate again and clean the git repository).

Feel free to check either generic_github or generic_gitlab to see what this plugin specifically generates.

Golang

When golang plugin is detected (a go.mod is present at root and is valid), it will generate the appropriate files around golang testing, makefiles, CI integration (in case CI option is given), etc.

Feel free to check either golang_github or golang_gitlab to see what this plugin specifically generates.

Helm

When helm plugin is detected (no_chart is either not provided or false), it will generate a specific helm chart capable of easily deploying cronjobs, jobs, workers or even chart dependencies.

Feel free to check helm to see what this plugin specifically generates.

License

When license plugin is detected (license is provided in .craft root file and is valid), it will generate the appropriate license file.

Nodejs

When nodejs plugin is detected (a package.json is present at root and is valid), it will the appropriate files around nodejs testing, integration, etc.

Feel free to check either nodejs_github or nodejs_gitlab to see what this plugin specifically generates.

OpenAPI v2

When openapi_v2 plugin is detected (api is present in .craft and a go.mod is present at root and is valid), it will generate a go-swagger based API.

Additional files will be generated in internal to easily separate generated code from business code.

Feel free to check openapi_v2 to see what this plugin specifically generates.