@mountainpass/hooked-cli/schemas/hooked.yaml.schema-v1.json

A tool for runnable scripts

{
  "$id": "https://github.com/mountain-pass/hooked/cli/schemas/hooked.yaml.schema-v1.json",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "JSON Schema for 'Hooked' - a command line tool to manage scripts.",
  "description": "Manage and execute your scripts from a single place.",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "imports": {
      "description": "Specifies a `string[]` of file paths or http endpoints, of hooked configuration files. These files are (downloaded), loaded and merged into the current running configuration (in order).",
      "type": "array",
      "items": {
        "description": "A file path or http endpoint, resolving to a hooked configuration file. File paths support glob pattern matching.",
        "type": "string"
      }
    },
    "triggers": {
      "description": "Provides the ability to trigger jobs.",
      "$ref": "#/$defs/triggersGroup"
    },
    "plugin": {
      "description": "Provides the ability to use built-in plugins.",
      "type": "object",
      "properties": {
        "icons": {
          "description": "Makes pretty icons to differentiate executable scripts vs groups.",
          "type": "boolean"
        },
        "abi": {
          "description": "Scans for `*.json` files, and imports the contract methods as scripts.\nRequired environment variables:\n- PROVIDER_URL\n- PRIVATE_KEY (?)\n- BLOCK_NUMBER (?)",
          "type": "boolean"
        },
        "makefile": {
          "description": "Scans for a `Makefile` file, and imports the named tasks as scripts.",
          "type": "boolean"
        },
        "npm": {
          "description": "Scans for a `package.json` file, and imports the named scripts as scripts.",
          "type": "boolean"
        }
      }
    },
    "env": {
      "description": "Globally defined environment variables, which can be referenced inside `scripts`.",
      "$ref": "#/$defs/EnvironmentGroup"
    },
    "scripts": {
      "description": "Organises `$cmd`, `$path` and `$jobs_serial` objects, into a named hierarchy.",
      "$ref": "#/$defs/scriptsGroup"
    }
  },
  "$defs": {
    "cronSchedule": {
      "description": "A Cron schedule, including seconds. E.g. '0 0 * * * *'.",
      "type": "string"
    },
    "scriptReference": {
      "description": "A path to a script.",
      "type": "string"
    },
    "CronTrigger": {
      "description": "Used to trigger a job on a cron schedule.",
      "type": "object",
      "properties": {
        "$cron": {
          "$ref": "#/$defs/cronSchedule"
        },
        "$job": {
          "$ref": "#/$defs/scriptReference"
        }
      },
      "required": [
        "$cron",
        "$job"
      ]
    },
    "triggersGroup": {
      "description": "Organises triggers.",
      "type": "object",
      "additionalProperties": false,
      "patternProperties": {
        "^.*$": {
          "anyOf": [
            {
              "$ref": "#/$defs/CronTrigger"
            }
          ]
        }
      }
    },
    "scriptsGroup": {
      "description": "Organises `$cmd` objects, into a named hierarchy.",
      "type": "object",
      "additionalProperties": false,
      "patternProperties": {
        "^.*$": {
          "anyOf": [
            {
              "$ref": "#/$defs/JobsSerialScript"
            },
            {
              "$ref": "#/$defs/WritePathScript"
            },
            {
              "$ref": "#/$defs/EnvScript"
            },
            {
              "$ref": "#/$defs/CmdScript"
            },
            {
              "$ref": "#/$defs/scriptsGroup"
            }
          ]
        }
      }
    },
    "EnvironmentGroup": {
      "description": "A named group of environment variables.",
      "type": "object",
      "additionalProperties": false,
      "patternProperties": {
        "^.*$": {
          "$ref": "#/$defs/EnvironmentKeyVariable"
        }
      }
    },
    "EnvironmentKeyVariable": {
      "description": "An environment variable key / value pair.\nReserved environment variables:\n- SKIP_VERSION_CHECK (?)\n- DOCKER_SCRIPT (?)\n- SSH_SCRIPT (?)\n- NPM_SCRIPT (?)\n- MAKE_FILE (?)\n- MAKE_SCRIPT (?)",
      "type": "object",
      "patternProperties": {
        "^.*$": {
          "oneOf": [
            {
              "description": "Executes a command, and optionally provides output to environment variables or stdin.",
              "$ref": "#/$defs/CmdScript"
            },
            {
              "description": "Provides a prompt to the user, to select from a set of choices.",
              "$ref": "#/$defs/StdinScript"
            },
            {
              "description": "Resolves to a plain text string.\nResolves any `${..}` environment variables within the string.\nThrows an error if an environment variable is missing. Can be used to enforce presence of variables.",
              "type": "string"
            },
            {
              "description": "Resolves to a plain text string.",
              "type": "number"
            },
            {
              "description": "Resolves to a plain text string.",
              "type": "boolean"
            }
          ]
        }
      }
    },
    "JobsSerialScript": {
      "description": "Allows running multiple jobs, one after the other. Environment variables will be accumulated, and passed on to future jobs.",
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "$jobs_serial": {
          "description": "Allows running multiple jobs, one after the other. Environment variables will be accumulated, and passed on to future jobs.",
          "type": "array",
          "items": {
            "anyOf": [
              {
                "$ref": "#/$defs/scriptReference"
              },
              {
                "$ref": "#/$defs/WritePathScript"
              },
              {
                "$ref": "#/$defs/EnvScript"
              },
              {
                "$ref": "#/$defs/CmdScript"
              }
            ]
          }
        }
      },
      "required": [
        "$jobs_serial"
      ]
    },
    "WritePathScript": {
      "description": "Configuration for writing a file/folder.",
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "$path": {
          "description": "Sets the file/folder location.",
          "type": "string"
        },
        "$content": {
          "description": "Sets the contents of the file to match the string. If an object is provided, will attempt to serialise the content to match either Yaml or Json (using the file extension). If absent, treats the path as a folder. Content is utf-8.",
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "object"
            }
          ]
        },
        "$permissions": {
          "description": "Sets the read/write/execute access permissions on the file/folder.",
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "number"
            }
          ]
        },
        "$owner": {
          "description": "Sets the 'uid:gid' of the file/folder. (Note: must be numerical!).",
          "type": "string"
        },
        "$image": {
          "description": "If supplied, file will be written in this docker image container.",
          "type": "string"
        },
        "$ssh": {
          "description": "If supplied, file will be written in this remote server.",
          "type": "string"
        }
      },
      "required": [
        "$path"
      ]
    },
    "EnvScript": {
      "type": "object",
      "description": "Additional environment variables to resolve (added to global environment).",
      "properties": {
        "$env": {
          "description": "Additional environment variables to resolve (added to global environment).",
          "$ref": "#/$defs/EnvironmentKeyVariable"
        }
      },
      "required": [
        "$env"
      ]
    },
    "CmdScript": {
      "description": "Executes a command, and optionally provides output to environment variables or stdin.",
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "$env": {
          "description": "Additional environment variables to resolve (added to global environment). Resolved before $envNames",
          "$ref": "#/$defs/EnvironmentGroup"
        },
        "$envNames": {
          "description": "Additional environment group names to resolve ONLY when executing this command.",
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "$envFromHost": {
          "description": "If true, includes all environment variables from the host machine. (On by default for non-$ssh and non-$image commands.",
          "type": "boolean"
        },
        "$cmd": {
          "description": "The command to run. Supports multiline.",
          "type": "string"
        },
        "$errorMessage": {
          "description": "An error message to display, when the `$cmd` exits with a non-zero exit code.",
          "type": "string"
        },
        "$image": {
          "description": "If supplied, command will execute in this docker image container.",
          "type": "string"
        },
        "$ssh": {
          "description": "If supplied, command will execute in this remote server.",
          "type": "string"
        }
      },
      "required": [
        "$cmd"
      ]
    },
    "StdinScript": {
      "type": "object",
      "additionalProperties": false,
      "description": "Provides a prompt to the user, to select from a set of choices.",
      "properties": {
        "$ask": {
          "description": "The prompt provided to the user.",
          "type": "string"
        },
        "$default": {
          "description": "The default value provided to the user.",
          "type": "string"
        },
        "$choices": {
          "description": "Provides different choices to the user. Can be a multiline string, array, object, arrays of name/value objects, Scripts, etc.",
          "$ref": "#/$defs/stdinChoicesValue"
        },
        "$fieldsMapping": {
          "description": "For JSON arrays, name and value can be overridden by specifying alternative JSON paths.",
          "$ref": "#/$defs/fieldsMappingValue"
        },
        "$filter": {
          "description": "A regex filter to apply to the 'name' or values.",
          "type": "string"
        },
        "$sort": {
          "description": "Sorts the displayed 'name' values.",
          "enum": [
            "alpha",
            "alphaDesc",
            "none"
          ]
        }
      },
      "required": [
        "$ask"
      ]
    },
    "stdinChoicesValue": {
      "description": "Provides different choices to the user. Can be a multiline string, array, object, arrays of name/value objects, Scripts, etc.",
      "oneOf": [
        {
          "$ref": "#/$defs/CmdScript"
        },
        {
          "description": "A multiline string, each line will become a choice.",
          "type": "string"
        },
        {
          "description": "An array of string options, each entry will become a choice.",
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        {
          "description": "An array of name/value object, each entry will become a choice.",
          "type": "array",
          "items": {
            "type": "object"
          }
        }
      ]
    },
    "fieldsMappingValue": {
      "description": "For JSON arrays, name and value can be overridden by specifying alternative JSON paths.",
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "name": {
          "description": "A JSON path to the 'name' value.",
          "type": "string"
        },
        "value": {
          "description": "A JSON path to the 'value' value.",
          "type": "string"
        }
      }
    }
  }
}