jim

jim is a highly extensible task runner.

Concept

jim comes in two parts: the cli-command and the jim-core package.

jim-cli

The jim command is just a wrapper that makes the jim command globally available. When you run a jim command, it will look for a jim-runtime inside the current working directory and delegate the command to it.

jim-core (this package)

The jim-runtime can be installed via Composer or npm. Once you installed the package inside your project, you will be able to execute jim commands.

jim-core and jim-scripts

The jim-core packages comes with a pretty small set of pre-installed commands. The true power of jim lies in the concept of jim-scripts.

You can write your own commands as node- or shell-scripts and make them available to jim.

Installation

jim-cli

You can install the jim-command by executing the install.sh script inside the repository. You only need to do this once.

jim-core

Depending on your project, you can install jim-core with the following commands:

Note It is recommended to install jim-core as a dev-dependency

Node / npm

npm install -D @pnodev/jim-core

PHP / Composer

composer require --dev pnodev/jim-core

Configuration / Usage

You can provide project-specific configuration with a .jimrc file:

NODE_VERSION=20
DIR_JIM_SCRIPTS=./jim-scripts

| Variable | Description | |:------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | NODE_VERSION | if you set the node-version, jim will make sure to set the correct version via nvm before executing node commands. This is especially useful if you are switching a lot between projects that require different node versions. | | DIR_JIM_SCRIPTS | Makes node- or shell-scripts at the specified location available as jim-commands. |

You can add more project-specific variables here. All variables defined in .jimrc will be exposed to the commands, so you can use them in your scripts. You could e.g. add variables to define the path to your JavaScript files and use it inside a esbuild-task.

Writing custom commands

Custom commands can be written as shell scripts. The jim-runtime provides you with the following helpers for writing your scripts in a consistent manner:

Environment Variables

The following environment variables will be made available for your commands:

| Variable | Description | |:------------------|:------------------------------------| | DIR_JIM_SCRIPTS | The path to your jim-scripts folder | | DIR_CORE | The path to your jim-core package |

Note Additionally, all variables you defined in .jimrc will be available as well.

Utility functions

By importing the following script, you get access to a bunch of utility functions:

source "${DIR_CORE}/utils.sh"

Colors

To generate more pleasing terminal output, you can use the following variables to format your logs:

| Variable | Description | |:---------------|:-------------------------| | COLOR_RESET | Resets all formatting | | COLOR_YELLOW | Sets the color to yellow | | COLOR_BLUE | Sets the color to blue | | COLOR_GREEN | Sets the color to green | | COLOR_RED | Sets the color to red | | COLOR_CYAN | Sets the color to cyan | | COLOR_DIMMED | Dimms the output color | | COLOR_BOLD | Formats the output bold |

_log

The _log function provides a coherent output behaviour. It is recommended to use it for all logs. It accepts the output string as the first parameter and an optional second parameter to set the output color.

_log "This is a yellow string" "${COLOR_YELLOW}"

_ask

The _ask functions displays a prompt to which the user can answer with yes or no. A good usecase for this function is asking the user for confirmation before executing a potentially dangerous command:

source "${DIR_CORE}/utils.sh"

if _ask "This will overwrite the data on the deploy server, do you want to continue?"
then
  _log "… Stating update" "$COLOR_YELLOW"
  ddev updateDeploy
  _log "✓ update finished" "$COLOR_YELLOW"
  echo ""
fi

_box

The _box function will display a given string inside a box:

_box "I'm in a box"

┌──────────────┐
│ I'm in a box │
└──────────────┘

_invoke

The _invoke command can be used to start another jim-task as a subtask. E.g. if you have a build-task that should start both the build:css- and build:js-tasks, you could do the following:

source "${DIR_CORE}/utils.sh"

setNodeVersion

_invoke build:css
_invoke build:js

_announceTaskStart

Pre-formatted log for announcing that your task started.

_announceTaskStart "Building CSS"

[jim] 🚧 Building CSS

_announceTaskEnd

Pre-formatted log for announcing that your task finished.

_announceTaskEnd "CSS built in ${PATH_CSS_OUT}"

[jim] 💪 CSS built in Resources/Public/Css/main.min.css

setNodeVersion

Sets the node version to the one specified in .jimrc. This is useful if you need to call a node-script from inside a shell-script command.

source "${DIR_CORE}/utils.sh"

setNodeVersion
npm install

Removing jim-cli

If you want to remove the jim command from your system, simply execute the uninstall.sh script inside this repository.

License

MIT