README
¶
vai
A simple task runner. Imagine GitHub actions and Makefile had a baby.
[!CAUTION] This project is still in its early stages. Expect breaking changes.
Installation
go install github.com/Noxsios/vai/cmd/vai@latest
To update to the latest version:
rm $(which vai)
go install github.com/Noxsios/vai/cmd/vai@latest
Example
cat <<EOF > vai.yaml
echo:
- cmd: echo "\$message"
with:
message: \${{ input }}
echo-matrix:
- cmd: echo "\$message"
matrix:
message: ["Hello", "World!"]
remote-echo-short:
- uses: github.com/Noxsios/vai@main?task=simple#tasks/echo.yaml
with:
message: hello from main
EOF
$ vai echo --with message="Hello World!"
echo "$message"
Hello World!
$ vai echo-matrix
echo "$message"
Hello, World!
echo "$message"
General Kenobi!
Learn more w/ vai --help
Schema Validation
Enabling schema validation in VSCode:
"yaml.schemas": {
"https://raw.githubusercontent.com/Noxsios/vai/main/vai.schema.json": "vai.yaml",
},
Per file basis:
# yaml-language-server: $schema=https://raw.githubusercontent.com/Noxsios/vai/main/vai.schema.json
Documentation
¶
Overview ¶
Package vai provides a simple task runner.
Index ¶
- Constants
- Variables
- func ConfirmSHAOverwrite() (bool, error)
- func IsHashMismatch(err error) bool
- func Logger() *log.Logger
- func ParseOutputFile(outFilePath string) (map[string]string, error)
- func PerformLookups(outer, local, persisted With, outputs CommandOutputs, mi MatrixInstance) (With, With, error)
- func Run(wf Workflow, taskName string, outer With) error
- func RunUses(uses string, with With) error
- func SetLogLevel(level log.Level)
- func Validate(wf Workflow) error
- func WorkFlowSchema() *jsonschema.Schema
- type CacheIndex
- type CommandOutputs
- type Matrix
- type MatrixInstance
- type Operation
- type Step
- type Store
- type Task
- type With
- type WithEntry
- type Workflow
Constants ¶
const (
// CacheEnvVar is the environment variable for the cache directory.
CacheEnvVar = "VAI_CACHE"
)
const DefaultFileName = "vai.yaml"
DefaultFileName is the default file name
const DefaultTaskName = "default"
DefaultTaskName is the default task name
const UsesPrefix = "pkg:vai/"
UsesPrefix is the prefix for remote tasks.
Variables ¶
var ErrHashMismatch = fmt.Errorf("hash mismatch")
ErrHashMismatch is returned when the hash of the stored file does not match the hash in the index.
var Force = false
Force is a global flag to bypass SHA256 checksum verification for cached remote files.
var TaskNamePattern = regexp.MustCompile("^[_a-zA-Z][a-zA-Z0-9_-]*$")
TaskNamePattern is a regular expression for valid task names, it is also used for step IDs
Functions ¶
func ConfirmSHAOverwrite ¶
ConfirmSHAOverwrite asks the user if they want to overwrite the SHA and bypass the check.
func IsHashMismatch ¶
IsHashMismatch returns true if the error is a hash mismatch error.
func ParseOutputFile ¶ added in v0.1.1
ParseOutputFile parses the output file of a step
func PerformLookups ¶ added in v0.1.2
func PerformLookups(outer, local, persisted With, outputs CommandOutputs, mi MatrixInstance) (With, With, error)
PerformLookups does the following:
1. Templating: executes the `input`, `default`, `persist`, and `from` functions against the `outer` and `local` With maps
2. Merging: merges the `persisted` and `local` With maps, with `local` taking precedence
3. MatrixInstance: merges the `mi` MatrixInstance into the result, with `mi` taking precedence
func Run ¶
Run executes a task in a workflow with the given inputs.
For all steps that have a `uses` step, this function will be called recursively.
func WorkFlowSchema ¶ added in v0.1.4
func WorkFlowSchema() *jsonschema.Schema
WorkFlowSchema returns a JSON schema for a vai workflow
Types ¶
type CacheIndex ¶
type CacheIndex struct {
Files []struct {
Name string `json:"name"`
Digest string `json:"digest"`
} `json:"files"`
}
CacheIndex is a list of files and their digests.
func (*CacheIndex) Add ¶
func (c *CacheIndex) Add(key, value string)
Add adds an entry to the index.
If the key already exists in the index and the value is the same, nothing will happen.
If the key already exists in the index and the value is different, the key will be removed and re-added.
If the key does not exist in the index, it will be added.
func (CacheIndex) Find ¶
func (c CacheIndex) Find(key string) (string, bool)
Find returns the digest of a file by name and a boolean indicating if the file was found.
func (*CacheIndex) Remove ¶
func (c *CacheIndex) Remove(key string)
Remove removes an entry from the index.
type CommandOutputs ¶ added in v0.1.1
CommandOutputs is a map of step IDs to their outputs.
It is currently NOT goroutine safe.
type Matrix ¶
Matrix is a map[]{string|int|bool}
Type safety cannot currently be enforced at compile time, and is instead enforced at runtime using JSON schema validation
example (YAML):
matrix: os: [linux, darwin] arch: [amd64, arm64]
type MatrixInstance ¶
MatrixInstance is a map[string]{string|int|bool}
Type safety cannot currently be enforced at compile time, and is instead enforced at runtime using JSON schema validation
example:
mi := MatrixInstance{
"os": "linux",
"latest": true,
}
type Operation ¶
type Operation int
Operation is an enum for the type of operation a step is performing
type Step ¶ added in v0.1.1
type Step struct {
// CMD is the command to run
CMD string `json:"cmd,omitempty"`
// Uses is a reference to a remote task
Uses string `json:"uses,omitempty"`
// With is a map of additional parameters for the step/task call
With `json:"with,omitempty"`
// Matrix is a matrix of parameters to run the step/task with
Matrix `json:"matrix,omitempty"`
// ID is a unique identifier for the step
ID string `json:"id,omitempty"`
// Description is a description of the step
Description string `json:"description,omitempty"`
}
Step is a single step in a task
While a step can have both `cmd` and `uses` fields, only one of them can be set at a time.
This is enforced by JSON schema validation.
TODO: - add `if` and `continue-on-error` fields? - add `timeout` field?
func (Step) JSONSchemaExtend ¶ added in v0.1.4
func (Step) JSONSchemaExtend(schema *jsonschema.Schema)
JSONSchemaExtend extends the JSON schema for a step
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store is a cache for storing and retrieving remote workflows.
func DefaultStore ¶
DefaultStore creates a new store in the default location:
$VAI_CACHE || $HOME/.vai/cache
type With ¶
With is a map of string keys and WithEntry values used to pass parameters to called tasks and within steps
Each key will be mapped to an equivalent environment variable when the command is run. eg. `with: {foo: bar}` will be passed as `foo=bar` to the command.
type Workflow ¶
Workflow is a map of tasks, where the key is the task name
This is the main structure that represents `vai.yaml` and other vai workflow files
func FetchIntoStore ¶ added in v0.1.3
FetchIntoStore fetches and stores a remote workflow into a given store.
func ReadAndValidate ¶ added in v0.1.4
ReadAndValidate reads and validates a workflow
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package cmd provides the root command for the vai CLI.
|
Package cmd provides the root command for the vai CLI. |
|
vai
Package main is the entry point for the application
|
Package main is the entry point for the application |
|
Package main provides the entry point for the application.
|
Package main provides the entry point for the application. |