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.
What you need
Section titled “What you need”- 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.
The code
Section titled “The code”Save the script as ~/slice-sheets/generate.sh, outside the application’s repository, and make it executable with chmod +x ~/slice-sheets/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 0fi
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"Run it once, offline
Section titled “Run it once, offline”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.
-
Save the example backend order as
~/order.json. -
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--verifyis where your build and tests go, for exampledotnet testornpm test. Every--verifycommand runs after the generator; one that fails turns the outcome intofailed. -
Check the result.
~/outcome.jsonsaysbuiltand listsslices/Invoicing/PayInvoice.md, andgit logshows the commit. Run the same command again: the sheet is unchanged, so the outcome isnothingToDoand nothing is committed.
Run it for real
Section titled “Run it for real”-
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> -
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" -
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.
Keep it running
Section titled “Keep it running”On macOS and Linux, install the loop as a user service, from the clone of the repository:
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.
How it works
Section titled “How it works”Reading the order
Section titled “Reading the order”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.
Writing the sheet
Section titled “Writing the sheet”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.
Nothing to do
Section titled “Nothing to do”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 outcome
Section titled “The outcome”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.
Failing
Section titled “Failing”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.
Related
Section titled “Related”- Build with a generator: the generator contract, step by step.
- Deterministic with AI on top: a generator that writes the structure, and a coding agent that completes it.
- Build orders and outcomes: everything in the order the generator reads.
- Use the reference builder: every
cratis buildcommand, and build kits.