tusk.schema.json

{
	"$defs": {
		"argClause": {
			"additionalProperties": false,
			"description": "A command-line argument definition for the task.",
			"properties": {
				"type": {
					"$ref": "#/$defs/type",
					"title": "type"
				},
				"usage": {
					"description": "A one-line summary of the argument.",
					"title": "usage",
					"type": "string"
				},
				"values": {
					"description": "A predefined set of acceptable values to provide for the argument.",
					"items": {
						"$ref": "#/$defs/value"
					},
					"title": "values",
					"type": "array"
				}
			},
			"type": "object"
		},
		"argsClause": {
			"additionalProperties": {
				"$ref": "#/$defs/argClause"
			},
			"description": "The set of command-line arguments that must be provided to the task.",
			"type": "object"
		},
		"commandClause": {
			"description": "The command or commands to execute using the global interpreter.",
			"oneOf": [
				{
					"$ref": "#/$defs/commandItem"
				},
				{
					"items": {
						"$ref": "#/$defs/commandItem"
					},
					"type": "array"
				}
			]
		},
		"commandItem": {
			"description": "The command to execute using the global interpreter.",
			"oneOf": [
				{
					"type": "string"
				},
				{
					"additionalProperties": false,
					"properties": {
						"dir": {
							"title": "dir",
							"type": "string"
						},
						"exec": {
							"description": "The command to execute using the global interpreter.",
							"title": "exec",
							"type": "string"
						},
						"print": {
							"description": "The text that will be printed when the command is executed.",
							"title": "print",
							"type": "string"
						},
						"quiet": {
							"default": false,
							"description": "Whether to silence the text/hint before execution.\nCommand output will still be printed.\n",
							"title": "quiet",
							"type": "boolean"
						}
					},
					"required": [
						"exec"
					],
					"type": "object"
				}
			]
		},
		"defaultClause": {
			"description": "The default value to use if the value is not otherwise set.\nIf multiple values are provided, the first `when` that evaluates to true will be used as the default value, with an omitted `when` always considered true.\n",
			"oneOf": [
				{
					"$ref": "#/$defs/defaultItem"
				},
				{
					"items": {
						"$ref": "#/$defs/defaultItem"
					},
					"type": "array"
				}
			],
			"title": "default"
		},
		"defaultItem": {
			"description": "A default value to use if the value is not otherwise set.\nIf a `when` clause is provided, the value will be used if and only if the condition evaluates to true.\n",
			"oneOf": [
				{
					"$ref": "#/$defs/value"
				},
				{
					"additionalProperties": false,
					"oneOf": [
						{
							"required": [
								"command"
							]
						},
						{
							"required": [
								"value"
							]
						}
					],
					"properties": {
						"command": {
							"description": "A command to run via the global interpreter.\nThe value of stdout will be used as the value.\n",
							"title": "command",
							"type": "string"
						},
						"value": {
							"$ref": "#/$defs/value",
							"title": "value"
						},
						"when": {
							"$ref": "#/$defs/whenClause",
							"title": "when"
						}
					},
					"type": "object"
				}
			]
		},
		"envFile": {
			"description": "A file to load environment variables from.\nFile paths specified are relative to the configuration file.\n",
			"oneOf": [
				{
					"type": "string"
				},
				{
					"additionalProperties": false,
					"properties": {
						"path": {
							"description": "The path to an environment file relative to the configuration file.\n",
							"type": "string"
						},
						"required": {
							"default": true,
							"description": "Whether the file is required to exist.",
							"type": "boolean"
						}
					},
					"required": [
						"path"
					],
					"type": "object"
				}
			]
		},
		"envFileClause": {
			"description": "The files to load environment variables from.\nIf no value is specified, environment variables will be read from an optional `.env` file automatically.\n",
			"oneOf": [
				{
					"$ref": "#/$defs/envFile"
				},
				{
					"items": {
						"$ref": "#/$defs/envFile"
					},
					"type": "array"
				}
			]
		},
		"option": {
			"additionalProperties": false,
			"allOf": [
				{
					"not": {
						"required": [
							"private",
							"environment"
						]
					}
				},
				{
					"not": {
						"required": [
							"private",
							"required"
						]
					}
				},
				{
					"not": {
						"required": [
							"private",
							"short"
						]
					}
				},
				{
					"not": {
						"required": [
							"private",
							"values"
						]
					}
				},
				{
					"not": {
						"required": [
							"required",
							"default"
						]
					}
				}
			],
			"description": "A command-line option for the task.\nOptions may be set by CLI flag, environment variable, or a configured default value, in that order.\n",
			"properties": {
				"default": {
					"$ref": "#/$defs/defaultClause",
					"title": "default"
				},
				"environment": {
					"description": "An environment variable that can be used to set the value.",
					"title": "environment",
					"type": "string"
				},
				"private": {
					"default": false,
					"description": "Whether the option is configurable by CLI or environment variable.",
					"title": "private",
					"type": "boolean"
				},
				"required": {
					"default": false,
					"title": "required",
					"type": "boolean"
				},
				"rewrite": {
					"description": "The text to use for interpolation for boolean values.",
					"title": "rewrite",
					"type": "string"
				},
				"short": {
					"description": "The one-letter option name.\nShort flags can be passed using a single hyphen (e.g., -a) or combined with other short flags (e.g., -abc).\n",
					"maxLength": 1,
					"minLength": 1,
					"title": "short",
					"type": "string"
				},
				"type": {
					"$ref": "#/$defs/type",
					"title": "type"
				},
				"usage": {
					"description": "A one-line summary of the option.",
					"title": "usage",
					"type": "string"
				},
				"values": {
					"description": "A predefined set of acceptable values to provide for the option.",
					"items": {
						"$ref": "#/$defs/value"
					},
					"title": "values",
					"type": "array"
				}
			},
			"type": "object"
		},
		"optionsClause": {
			"additionalProperties": {
				"$ref": "#/$defs/option"
			},
			"description": "The set of command-line options that may be provided to the task.",
			"type": "object"
		},
		"runClause": {
			"anyOf": [
				{
					"$ref": "#/$defs/runItem"
				},
				{
					"items": {
						"$ref": "#/$defs/runItem"
					},
					"type": "array"
				}
			],
			"description": "The behavior of the task."
		},
		"runItem": {
			"oneOf": [
				{
					"$ref": "#/$defs/commandClause"
				},
				{
					"additionalProperties": false,
					"oneOf": [
						{
							"required": [
								"command"
							]
						},
						{
							"required": [
								"set-environment"
							]
						},
						{
							"required": [
								"task"
							]
						}
					],
					"properties": {
						"command": {
							"$ref": "#/$defs/commandClause",
							"title": "run command"
						},
						"set-environment": {
							"$ref": "#/$defs/setEnvironmentClause",
							"title": "run set environment"
						},
						"task": {
							"$ref": "#/$defs/subTaskClause",
							"title": "run sub-task"
						},
						"when": {
							"$ref": "#/$defs/whenClause",
							"title": "run when"
						}
					},
					"type": "object"
				}
			]
		},
		"setEnvironmentClause": {
			"additionalProperties": {
				"type": [
					"string",
					"null"
				]
			},
			"description": "The environment variables to either set or unset.",
			"type": "object"
		},
		"stringOrArray": {
			"oneOf": [
				{
					"type": "string"
				},
				{
					"items": {
						"type": "string"
					},
					"type": "array"
				}
			]
		},
		"subTaskClause": {
			"description": "A sub-task to run as a part of the outer task definition.",
			"oneOf": [
				{
					"type": "string"
				},
				{
					"additionalProperties": false,
					"properties": {
						"args": {
							"description": "The argument values to pass to the sub-task.",
							"items": {
								"$ref": "#/$defs/value"
							},
							"title": "sub-task args",
							"type": "array"
						},
						"name": {
							"description": "The name of the sub-task to run.",
							"title": "sub-task name",
							"type": "string"
						},
						"options": {
							"additionalProperties": {
								"$ref": "#/$defs/value"
							},
							"description": "The option values to pass to the sub-task.",
							"title": "sub-task options",
							"type": "object"
						}
					},
					"required": [
						"name"
					],
					"type": "object"
				}
			]
		},
		"taskClause": {
			"description": "The task definition.",
			"oneOf": [
				{
					"$ref": "#/$defs/taskInclude"
				},
				{
					"$ref": "#/$defs/taskItem"
				}
			]
		},
		"taskInclude": {
			"additionalProperties": false,
			"properties": {
				"include": {
					"description": "The relative file path to the yaml task definition.\n",
					"title": "task include",
					"type": "string"
				}
			},
			"required": [
				"include"
			],
			"type": "object"
		},
		"taskItem": {
			"additionalProperties": false,
			"properties": {
				"args": {
					"$ref": "#/$defs/argsClause",
					"title": "task args"
				},
				"description": {
					"description": "The full description of the task. This may be a multi-line value.\n",
					"title": "task description",
					"type": "string"
				},
				"finally": {
					"$ref": "#/$defs/runClause",
					"description": "Logic to execute after a task's run logic has completed, whether or not that task was successful.\n",
					"title": "task finally"
				},
				"options": {
					"$ref": "#/$defs/optionsClause",
					"title": "task options"
				},
				"private": {
					"default": false,
					"description": "Whether the task can be ran directly.",
					"title": "task private",
					"type": "boolean"
				},
				"quiet": {
					"default": false,
					"description": "Whether to silence the text/hint before execution.\nCommand output will still be printed.",
					"title": "task quiet",
					"type": "boolean"
				},
				"run": {
					"$ref": "#/$defs/runClause",
					"title": "task run"
				},
				"usage": {
					"description": "A one-line summary of the task.",
					"title": "task usage",
					"type": "string"
				}
			},
			"required": [
				"run"
			],
			"type": "object"
		},
		"tasksClause": {
			"additionalProperties": {
				"$ref": "#/$defs/taskClause"
			},
			"description": "The list of defined tasks available.",
			"type": "object"
		},
		"type": {
			"description": "The type of the value.\n",
			"enum": [
				"int",
				"integer",
				"float",
				"float64",
				"double",
				"bool",
				"boolean",
				"string"
			]
		},
		"value": {
			"description": "The value of an arg or option.",
			"oneOf": [
				{
					"type": "number"
				},
				{
					"type": "boolean"
				},
				{
					"type": "string"
				}
			]
		},
		"valueList": {
			"description": "A set of possible values for an arg or option.",
			"oneOf": [
				{
					"$ref": "#/$defs/value"
				},
				{
					"items": {
						"$ref": "#/$defs/value"
					},
					"type": "array"
				}
			]
		},
		"whenClause": {
			"description": "A condition that controls whether its outer clause runs or not.\nEach individual item in the list of when clauses must pass for the check to be considered successful.\n",
			"oneOf": [
				{
					"$ref": "#/$defs/whenItem"
				},
				{
					"items": {
						"$ref": "#/$defs/whenItem"
					},
					"type": "array"
				}
			]
		},
		"whenItem": {
			"oneOf": [
				{
					"$ref": "#/$defs/value"
				},
				{
					"additionalProperties": false,
					"minProperties": 1,
					"properties": {
						"command": {
							"$ref": "#/$defs/stringOrArray",
							"description": "A command to run via the global interpreter.\nThe when clause will be considered a success if any of the commands exit with a status code of 0.\n",
							"title": "when command"
						},
						"environment": {
							"additionalProperties": {
								"$ref": "#/$defs/stringOrArray"
							},
							"description": "A set of environment variable values to check.\nThe when clause will be considered a success if any environment variable matches any of the provided values.\n",
							"title": "when environment",
							"type": "object"
						},
						"equal": {
							"additionalProperties": {
								"$ref": "#/$defs/valueList"
							},
							"description": "A set of arg or option values to check.\nThe when clause will be considered a success if any arg or option matches any of the provided values.\n",
							"title": "when equal",
							"type": "object"
						},
						"exists": {
							"$ref": "#/$defs/stringOrArray",
							"description": "A set of files to check for existence.\nThe when clause will be considered a success if any of the files exist.\n",
							"title": "when exists"
						},
						"not-equal": {
							"additionalProperties": {
								"$ref": "#/$defs/valueList"
							},
							"description": "A set of arg or option values to check negatively.\nThe when clause will be considered a success if any of the arg or option values do not match any of the provided values.\n",
							"title": "when not equal",
							"type": "object"
						},
						"not-exists": {
							"$ref": "#/$defs/stringOrArray",
							"description": "A set of files to check for non-existence.\nThe when clause will be considered a success if any of the files do not exist.\n",
							"title": "when not exists"
						},
						"os": {
							"$ref": "#/$defs/stringOrArray",
							"description": "A set of operating systems to check against.\nThe when clause will be considered a success if the current OS matches any of the provided operating systems.\n",
							"title": "when os"
						}
					},
					"type": "object"
				}
			]
		}
	},
	"$id": "https://github.com/rliebz/tusk/blob/main/tusk.schema.json",
	"$schema": "http://json-schema.org/draft-07/schema#",
	"additionalProperties": false,
	"properties": {
		"env-file": {
			"$ref": "#/$defs/envFileClause",
			"title": "env-file"
		},
		"interpreter": {
			"default": "sh -c",
			"description": "The interpreter to use for commands.\nThe interpreter is specified as an executable, which can either be an absolute path or available on the user's PATH, followed by a series of optional arguments.\nThe commands specified in individual tasks will be passed as the final argument.\n",
			"examples": [
				"node -e",
				"python3 -c"
			],
			"title": "interpreter",
			"type": "string"
		},
		"name": {
			"default": "tusk",
			"description": "The alias name to display in help text when using shell aliases to create a custom named CLI application.\n",
			"title": "name",
			"type": "string"
		},
		"options": {
			"$ref": "#/$defs/optionsClause",
			"description": "Shared options available to all tasks.\nAny shared variables referenced by a task will be exposed by command-line when invoking that task. Shared variables referenced by a sub-task will be evaluated as needed, but not exposed by command-line.\nTasks that define an argument or option with the same name as a shared task will overwrite the value of the shared option for the length of that task, not including sub-tasks.\n",
			"title": "shared options"
		},
		"tasks": {
			"$ref": "#/$defs/tasksClause",
			"title": "tasks"
		},
		"usage": {
			"default": "the modern task runner",
			"description": "The usage text to display in help text when using shell aliases to create a custom named CLI application.\n",
			"title": "usage",
			"type": "string"
		}
	},
	"title": "JSON schema for tusk configuration files",
	"type": "object"
}