feat: add the ability to modify the DOKKU_IMAGE in use for the herokuish builder

This is a "one-shot" ability, meaning that it is highly discouraged for multiple plugins to implement the triggers.

The `builder-create-dokku-image` trigger is meant to modify the base DOKKU_IMAGE that will be used to build an application. A good use of the hook is to inject system packages by:

- calculating an image tag from the set of system packages
- checking that the image doesnt already exist
- creating the image if it does not

As the output is sent to stdout, we have to find an alternative way of fetching the new DOKKU_IMAGE. The `builder-dokku-image` trigger can output an image tag based on the calculated image tag. If no tag is output, then the DOKKU_IMAGE is used as is.

Using this pattern, users can efficiently modify the base image in use for an app without duplicating the work on every push. This is especially useful for package installation, where packages are required for app building, but may take a long time and can be error prone.

docs/development/plugin-triggers.md

@@ -83,6 +83,36 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
 # TODO
 ```
 
+### `builder-create-dokku-image`
+
+- Description: Allows modification of the configured dokku-image
+- Invoked by: `dokku deploy`
+- Arguments: `$BUILDER_TYPE` `$APP` `$SOURCECODE_WORK_DIR` `$DOKKU_IMAGE`
+- Example:
+
+```shell
+#!/usr/bin/env bash
+
+set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
+
+# TODO
+```
+
+### `builder-dokku-image`
+
+- Description: Allows modification of the used dokku-image.
+- Invoked by: `dokku deploy`
+- Arguments: `$BUILDER_TYPE` `$APP` `$SOURCECODE_WORK_DIR` `$DOKKU_IMAGE`
+- Example:
+
+```shell
+#!/usr/bin/env bash
+
+set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
+
+# TODO
+```
+
 ### `builder-release`
 
 - Description: Triggers the artifact release process

plugins/builder-herokuish/builder-build

@@ -24,6 +24,10 @@ trigger-builder-build-builder-herokuish() {
   eval "$(config_export app "$APP")"
 
   DOKKU_IMAGE="$(config_get "$APP" DOKKU_IMAGE || echo "$DOKKU_IMAGE")"
+  plugn trigger builder-create-dokku-image "$BUILDER_TYPE" "$APP" "$SOURCECODE_WORK_DIR" "$DOKKU_IMAGE"
+  NEW_DOKKU_IMAGE=$(plugn trigger builder-dokku-image "$BUILDER_TYPE" "$APP" "$SOURCECODE_WORK_DIR" "$DOKKU_IMAGE")
+  [[ -n "$NEW_DOKKU_IMAGE" ]] && DOKKU_IMAGE="$NEW_DOKKU_IMAGE"
+
   CID=$(tar -c . | "$DOCKER_BIN" run "${DOCKER_RUN_LABEL_ARGS[@]}" $DOKKU_GLOBAL_RUN_ARGS -i -a stdin "$DOKKU_IMAGE" /bin/bash -c "mkdir -p /app && tar -xC /app")
   test "$("$DOCKER_BIN" wait "$CID")" -eq 0