Skip to content

Sample: a generator in Bash

This sample is a generator in one Bash script, with nothing but jq. It is a generator: the Cratis CLI runs it for every build order, and does everything else a builder does, from connecting to Studio to committing and reporting. See Build with a generator for how the two fit together.

For every slice in the order, the generator writes a Markdown sheet with the slice’s acceptance criteria to slices/<feature>/<slice>.md in the project, and reports what it wrote. The comment in the code marks where real code generation goes.

The TypeScript and C# samples do exactly the same thing, and write the same sheets. The language is your choice: anything the shell can start works.

  • The Cratis CLI, with cratis build.
  • Bash and jq 1.6 or later. On macOS, brew install jq; on Debian or Ubuntu, apt install jq.
  • A clean clone of the application’s repository.

Save the script as ~/slice-sheets/generate.sh, outside the application’s repository, and make it executable with chmod +x ~/slice-sheets/generate.sh.

generate.sh
#!/usr/bin/env bash
# Slice sheets: a generator for `cratis build`. For every slice in the build order it writes
# a Markdown sheet with the slice's acceptance criteria into the project.
set -euo pipefail
order="$STUDIO_BUILD_ORDER"
outcome="$STUDIO_BUILD_OUTCOME"
fail() {
jq -n --arg error "$1" '{ kind: "failed", error: $error, retryable: false }' > "$outcome"
exit 0
}
safe() {
case "$1" in
"" | *[!A-Za-z0-9._\ -]* | .*) return 1 ;;
esac
}
feature=$(jq -r '.scope.feature.name' "$order")
safe "$feature" || fail "The feature name '$feature' cannot be used as a folder name."
files=()
while IFS=$'\t' read -r id name; do
safe "$name" || fail "The slice name '$name' cannot be used as a file name."
file="slices/$feature/$name.md"
# This is where real generation goes: run your code generator or templates for the
# slice here and write the files they produce. This sample writes one sheet per slice.
sheet=$(jq -r --arg id "$id" '
(.scope.slices[] | select(.id == $id)) as $slice
| "# \($slice.name)",
"",
"A \($slice.type) slice in \(.scope.feature.name).",
"",
"## Acceptance criteria",
(.specifications[] | select(.sliceId == $id)
| "", "### \(.name)", "",
"- Given \(if (.given | length) > 0 then .given | join(", ") else "nothing" end)",
"- When \(.when)",
"- Then \(.then | join(", "))")
' "$order")
if [ -f "$file" ] && [ "$(cat "$file")" = "$sheet" ]; then
continue
fi
mkdir -p "$(dirname "$file")"
printf '%s\n' "$sheet" > "$file"
files+=("$file")
done < <(jq -r '.scope.slices[] | [.id, .name] | @tsv' "$order")
if [ "${#files[@]}" -eq 0 ]; then
jq -n '{ kind: "nothingToDo" }' > "$outcome"
exit 0
fi
jq '{
kind: "built",
files: $ARGS.positional,
specifications: [.specifications[] | { id, result: "notRun" }],
assumptions: ["Wrote a slice sheet for each slice; no code was generated."]
}' "$order" --args "${files[@]}" > "$outcome"

cratis build once runs the generator on an order from a file, without connecting to Studio, and commits what it built just as a real build does.

  1. Save the example backend order as ~/order.json.

  2. In the clone of the repository, run the generator on it:

    Terminal window
    cratis build once --order ~/order.json --exec "$HOME/slice-sheets/generate.sh" --verify "test -d slices" --outcome ~/outcome.json

    --verify is where your build and tests go, for example dotnet test or npm test. Every --verify command runs after the generator; one that fails turns the outcome into failed.

  3. Check the result. ~/outcome.json says built and lists slices/Invoicing/PayInvoice.md, and git log shows the commit. Run the same command again: the sheet is unchanged, so the outcome is nothingToDo and nothing is committed.

  1. Register the machine with your organization, once, and have a maintainer approve it with the code it shows. See Connect a builder and approve it.

    Terminal window
    cratis build connect --studio --organization <your organization>
  2. In the clone of the repository, start the build loop with the generator:

    Terminal window
    cratis build run --exec "$HOME/slice-sheets/generate.sh" --verify "test -d slices"
  3. In Studio, choose the builder for the application, and mark a slice Ready for implementation. The terminal shows the generator running, the commit, and how Studio settled the slice.

The CLI pushes each commit with your own Git credentials. Add --no-push to keep the commits local, or --once to stop after one slice.

On macOS and Linux, install the loop as a user service, from the clone of the repository:

Terminal window
cratis build service install --exec "$HOME/slice-sheets/generate.sh" --verify "test -d slices"

It starts when you sign in and restarts when it stops. cratis build service status says where its output goes, and cratis build service uninstall removes it.

jq reads the feature name and, one line per slice, the slice’s id and name from the file STUDIO_BUILD_ORDER names. The script runs in the project folder, so the paths it writes are relative to the project.

A second jq program builds the sheet for one slice: its name and type, then each specification whose sliceId matches, as Given, When and Then. This is where your own generation goes: call a code generator, fill templates, or write the command and event files for the slice.

A sheet that is already in the project with the same content is skipped. When every sheet is unchanged, the script reports nothingToDo, so the CLI makes no empty commit.

The last jq writes built with the files the script wrote, each specification as notRun (the sample runs no tests), and one assumption. The CLI adds the order’s id, the contract version and the commit.

A feature or slice name that cannot be a file name makes fail write a failed outcome with retryable set to false: another attempt would fail the same way. The script still exits with 0, because it wrote an outcome. If the script itself crashes, set -e makes it exit with an error, and the CLI reports a failure that Studio retries.