nordisk/dwarves

status badge — for idiots

Class: for-idiots · the zero-knowledge walkthrough. What it IS: status-badge-design.md · how to use it: status-badge-guide.md.

What is a badge?

You have seen them on project pages: a little coloured pill that says build │ passing in green, or build │ failing in red. It tells you at a glance whether the last build worked. That pill is just a small SVG image.

What did we add?

dwarves already knew how to draw the pill, but nothing could ask it to. Now a command can:

dwarves badge smoke-ci

This looks up the pipeline called smoke-ci, finds its most recent run, and prints the pill as SVG text. Green if it passed, red if it failed, grey if there is no run yet.

How it works, step by step

1. dwarves keeps a little logbook of every run it did (a file of one line per run).
2. badge reads that logbook and finds the newest line for your pipeline.
3. It turns that run's result into a colour and a word (passing / failing / …).
4. It draws the pill and prints it.

If you point it at a server instead (--server ...), the server does exactly the same three steps on its own logbook and sends the pill back. Same drawing code, so the pill looks identical either way.

The three outcomes

• It passed → green pill, the command finishes "happy" (exit code 0).
• It failed / is running → red or amber pill, exit code 1.
• No run yet → grey "unknown" pill, exit code 2. This is not an error! A brand-new pipeline just has nothing to report yet.

Where does the pill go?

Save it to a file and show it anywhere:

dwarves badge smoke-ci -o badge.svg

Then <img src="badge.svg"> in a web page, or paste it into a dashboard. Because the pill is fully self-contained, it needs nothing from the internet to display.