oiyouyeahyou / regisseur

CLI utility to help running manual workflows by prompting the user for a confirmation at each step.

regisseur 📜

A person who stages a theatrical production.

Features

Some not entirely automated processes or sensitive workflows still rely on manual steps usually described in text documents which can be hard to follow, where it is easy to miss a step or get lost in the process.

regisseur is a small utility allowing you to describe such workflows in a simple, human-readable format called plays and automatically prompt you for every step or act of a play and wait for a confirmation keyword before proceeding to the next one.

• Human-readable play in HJSON format
• Resumability of a play (i.e. you can resume a play from any given act)
• Configurable confirmation keyword (done by default)
• Restrict a play to a specific Git branch (e.g. main or develop)
• Restrict a play to a clean Git working tree (i.e. no uncommited changes)

Usage

You can either add regisseur to your project and invoke it with your favorite package manager (or through a script entry in your project's package.json file):

$ pnpm add -D regisseur
$ pnpm regisseur …

or use it directly with npx or pnpx:

$ pnpx regisseur …

Commands

Run a play

To run a play, you can simply invoke regisseur and optionaly specify the play to run:

$ pnpx regisseur [play]

Note The play argument can either be the path to a play file, the file name of a play file located in the plays directory, or the name of a play specified in the play itself. This argument can also be omitted to either play the default.play file in the plays directory or the only file in this directory if you have only one play in your project.

Resume a play

You can resume a play from a given step or act by specifying its number with the -c, --continue option:

$ pnpx regisseur [play] -c <actNumber>

List all plays

To quickly list all plays in your project, you can use the list command:

$ pnpx regisseur list

Validate a play

To validate a play, you can use the validate command:

$ pnpx regisseur validate [play]

Note The play argument can either be the path to a play file, the file name of a play file located in the plays directory, or the name of a play specified in the play itself. This argument can also be omitted to either play the default.play file in the plays directory or the only file in this directory if you have only one play in your project.

Play files

Play files are files located in the plays directory with the .play extension using the HJSON format.

To run a default play when running the regisseur command without any arguments, you can use the default.play file.

Global options

Name

A play can be a given a human-readable name:

{
  name: Release the thing
}

Confirmation keyword

By default, an act can be validated using the done keyword but you can specify a different keyword for an entire play:

{
  confirmation: ok
}

Git branch restriction

A play can be restricted to a specific Git branch:

{
  branch: main
}

Git clean working tree restriction

A play can be restricted to a clean Git working tree:

{
  clean: true
}

Acts

The various steps or acts of a play are described using the acts property. Each act is composed of a title and scenes describing how to complete the act:

{
  name: Release the thing

  acts: [
    {
      title: Build the thing
      scenes: [
        Do the first thing
        Do the second thing
        Do the third thing
      ]
    }
    {
      title: Publish the thing
      scenes: [
        Do this
        Do that
        Run this thing
      ]
    }
  ]
}

An act can also temporarily override the confirmation keyword:

{
  acts: [
    {
      title: Do that thing
      confirmation: ok
      scenes: [
        Do this
        Do that
      ]
    }
  ]
}

License

Licensed under the MIT License, Copyright © HiDeoo.

See LICENSE for more information.