fun_ci 2.0.0-x86_64-linux

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 98e558ae7dc888aac4569f5c7845765ac85c6edb2fae4da54f138777dd25b087
+  data.tar.gz: d8c10643d2f900cdff1779d8d94ffdc11c455b6277c8bc40ef0f194e97e31b48
+SHA512:
+  metadata.gz: 8524f64bd537280fcf9e7411bd3772a1664ba7854a1015cff2edf8a1a5c6230e70abd20c9e2821045a03520f67ba754a9ee0e0549d4b4bc356a513d7b48c3c8c
+  data.tar.gz: 2443708f11f8da5dfc6c150ffb995a89c072f86615a4c832f450e2776e76fdbd3958f7a5a9c99da404f4615a60c525a59e12eabeb7fb2d0ad627f7d80916b9c3

data/CHANGELOG.md

@@ -0,0 +1,294 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [2.0.0] - 2026-09-29
+
+fun-ci 2.0 has two ways in. People watch a new console, drawn by a Rust
+renderer in 24-bit colour, with a scene for each milestone a run passes. Coding
+agents and scripts ask with new commands (`status`, `wait`, `why`, `runs`,
+`events`) that answer with exit codes and keep enough of each failure to say
+why it failed without running the suite again. Pipelines now run in git
+worktrees at the commit they test, started after the commit rather than
+before it. See "Upgrading to 2.0" in the README.
+
+### Changed
+- The hook that runs a pipeline in the background is now `post-commit`, so it
+  tests the commit you just made; the `pre-commit` hook tested the commit
+  before it. `fun-ci install-hooks` writes `post-commit` and `pre-push`, and
+  removes the `pre-commit` hook fun-ci 1.x wrote. A `pre-commit` hook of your
+  own is left alone, and if it still calls fun-ci, `fun-ci check` warns you
+  to take that out. Run `fun-ci install-hooks` again to update your hooks;
+  until you do, `fun-ci check` warns that each run tests the commit before
+  yours.
+- The pre-push hook waits for the fast verdict of each commit the push sends
+  (`fun-ci wait SHA --need fast`) instead of running the pipeline again, so a
+  push after a finished post-commit run goes through at once. It reads the
+  commits from what git passes it, so pushing a branch other than the one
+  checked out tests the right commits.
+- Every pipeline runs in a git worktree of its own, checked out at the commit
+  it tests, under `.git/fun-ci/worktrees/`. Before, the stages ran in your
+  checkout while you kept editing it. Ignored files such as `vendor/bundle`
+  stay in a worktree from one run to the next. The stage scripts come from
+  the commit too, unless it has no `.fun-ci/`, in which case the checkout's
+  are used. Two pipelines run at once by default; set `worktree_slots: 3` (or
+  any number above 0) in `.fun-ci/config` for more.
+- fun-ci keeps its database in `$XDG_STATE_HOME/fun-ci/`, or
+  `~/.local/state/fun-ci/` without it, instead of under `$TMPDIR`, so every
+  process of a user finds the same database, including an agent in a sandbox
+  with a `TMPDIR` of its own. Runs recorded by 1.x are not carried over. The
+  state directory is readable by its user alone (0700).
+- A newer commit cancels an older unfinished run on its branch only in its own
+  project, never a run an agent is waiting on, and never a run of the same
+  commit.
+- `fun-ci console` is drawn by a separate program, `fun-ci-renderer`, written
+  in Rust. The gems for Linux (x86_64, aarch64, musl) and macOS (arm64,
+  x86_64) include it. Elsewhere, install it with `cargo install
+  fun-ci-renderer` or point `FUN_CI_RENDERER` at a copy you built; without
+  it, `console` says so and every other command works as before. What goes
+  wrong between the two ends up in `.fun-ci/console.log`, since the renderer
+  owns the terminal.
+- The console's header is a picture rather than ASCII art: soft light,
+  gradients and particles in 24-bit colour across the whole width, or the
+  nearest of 256 colours when `COLORTERM` doesn't say `truecolor` or `24bit`.
+  Only the parts that change are sent to the terminal.
+- The header plays a scene for each milestone a run passes, each milestone
+  with scenes of its own, so you can tell which it was without reading: a teal
+  sweep, ripple or spirit level for lint; amber blocks, gears or a ringing
+  anvil for the build; a lightning strike, YAY or a jump to warp speed for the
+  fast suite; fireworks, a trophy, dancing leprechauns or a sunrise for the
+  whole run; an explosion or shattering glass for a failure. Scenes queue and
+  each plays to its end, so a failure no longer cuts a celebration short, and
+  a run gets one failure scene however many of its stages fail.
+- When the scenes are done, the header rests on how the latest run went: a
+  calm dusk with a tick after a pass, a pulsing hazard sign after a failure.
+  Five minutes after the latest run finished it goes quiet: a starry night,
+  an aurora, fireflies, a fire in a medieval stone hearth with a storm at the
+  window, a moonlit island with a palm, or snowfall over pines, a different
+  one every five minutes while nothing runs, with a small lamp in the corner
+  that stays green after a pass and flickers red after a failure. The streak
+  ("7 in a row!", or "streak broken") sits in the top right.
+- The console's board fits the terminal's height and scrolls to keep the
+  cursor on screen.
+- The console's cancel prompt names the run it would cancel, as in
+  `Cancel feat/search (d4e5f67)? y / n`.
+- With no runs yet, the console suggests `fun-ci init --everything`. It used to
+  suggest `fun-ci trigger HEAD`, which fails without a branch, and
+  `fun-ci install-hook pre-push`, which does not exist.
+- When a stage fails, `fun-ci trigger` says what to do next, such as "Fix the
+  failing tests above, then try again."
+- A project's colour in the console stays the same from one start to the next.
+
+### Added
+- `fun-ci status [REV]` says where a commit's run stands, stage by stage, and
+  exits with a verdict an agent can branch on: 0 passed, 1 failed, 2 over
+  budget, 3 undecided, 4 superseded, 5 no run, 64 usage error. `--need
+  build|fast|all` says which stages must pass (fast by default), and `--json`
+  prints one JSON document.
+- `fun-ci wait [REV]` waits for that verdict and exits with it: as soon as the
+  stages `--need` names have passed, or at the first of them to fail or
+  overrun. `--within 30s` gives up undecided (exit 3). A commit with no run
+  after 5 seconds gets one started. `wait` on a superseded run exits 4 naming
+  the newer commit, and `--follow-branch` moves on to that commit's run.
+- `fun-ci runs` lists the project's recent runs, one line each; `-n N`,
+  `--branch NAME` and `--json`.
+- `fun-ci events` prints the project's runs' events as JSON lines (run
+  started, stage finished, run finished, run superseded); `--follow` keeps
+  printing them as they happen, and `--only failures` keeps to failed or
+  over-budget stages and superseded runs.
+- After each commit, the hook's output ends with the `fun-ci wait` command
+  that gets its verdict, and `fun-ci init` adds a short section to the
+  project's `AGENTS.md` (or `CLAUDE.md` when that is the only one) telling
+  agents to run it in the background.
+- `fun-ci why [REV] [STAGE]` prints everything fun-ci kept about a failed
+  stage: how it exited, how long it took against its budget, each reported
+  failure with its whole message and its own output, what the extractors
+  picked out, and the last lines of its output. `status` and `wait` end with
+  a digest of it and the `why` command. `why --raw` prints the stage's whole
+  output, kept for a project's 10 newest runs as its first 1 MB and last
+  7 MB, compressed. The end of a failed stage's output (200 lines, at most
+  64 KB) is kept for the 50 newest.
+- A `junit-files` entry under `evidence:` keeps each failure in the JUnit XML
+  a stage wrote (`build/test-results/**/*.xml`, `target/surefire-reports/*.xml`),
+  with the output each failure printed, and leaves alone reports an earlier
+  run left behind. `status --json` gives them to a program. fun-ci now depends
+  on `rexml` to read them.
+- Every stage script finds its stage's name in `FUN_CI_STAGE`.
+- Secrets are masked before fun-ci keeps anything a stage printed: the value
+  of any variable in the stage's environment whose name holds TOKEN, SECRET,
+  PASSWORD, PASSWD, API_KEY, PRIVATE_KEY or CREDENTIAL (8 characters or more)
+  shows as `[masked:NAME]`, and GitHub, AWS and Slack tokens, private keys and
+  `Authorization:` headers as `[masked]`. `mask:` under `evidence:` adds
+  patterns.
+- Presets pick out a tool's failures from a stage's output, for 34 tools,
+  each checked against the recorded output of a real failing run: rspec,
+  Minitest, Gradle, Maven, pytest, unittest, Jest, Vitest, Mocha, Node's test
+  runner, Bun, Deno, go test, cargo test, dotnet test, PHPUnit, ExUnit, swift
+  test, dart test, GoogleTest, tsc, ESLint, RuboCop, Ruff, mypy, go build,
+  rustc, gcc, ShellCheck, Perl's prove, and JSON logs from
+  logstash-logback-encoder, Elastic's ECS encoders, pino and structlog. With
+  no configuration fun-ci runs those whose marker files the project has
+  (`Gemfile`, `pom.xml`, ...) and whose tool's output the failure shows;
+  `fun-ci why` says why each was chosen and `fun-ci check` lists them.
+- `fun-ci init` writes stage scripts for every stack a preset reads, not only
+  Ruby and the JVM: rspec projects, Rust, Go, Elixir, Dart, Swift, PHP, .NET,
+  Python (uv, Poetry, pip), Deno, Bun, Node (pnpm, Yarn, npm), Perl, CMake and
+  make.
+- A project says what else to keep when a stage fails under `evidence:` in
+  `.fun-ci/config`, within a budget of 2 seconds: `grep`, `section` (with a
+  `preset:`), `log-file` (what the stage wrote to a log file, and only that),
+  `json-log` (records at or above a level, with the fields of a named preset or
+  your own), `junit-files` (JUnit XML a build tool writes in its own place),
+  and `run:`, your own extractor in any language, which gets the context as
+  JSON on stdin and prints text or JSON. `detect: false` and `skip: [name]`
+  turn presets off. The documents a `run:` extractor reads and prints are
+  pinned in `contract/evidence/`.
+- A stage that runs over budget says what it was doing: before the kill,
+  fun-ci lists its processes and the deepest one still running, and `status`
+  and `wait` lead with it (`fast ran over budget: running java ...
+  GradleWorkerMain (9.8s)`). A `run:` entry with `on: overrun` runs then, with
+  the stage's process group in `FUN_CI_PGID`, for a thread dump.
+- When another stage shared the worktree while a stage ran (lint beside
+  build, the slow suite beside the fast one), `fun-ci why` says so
+  (`alongside: slow`), since a log file may hold both stages' lines.
+- `fun-ci extract STAGE --output FILE` runs a stage's extractors against a
+  saved output and prints what `why` would, so an extractor can be tried
+  without making a commit.
+- `fun-ci check` reports a mistake under `evidence:` or a `run:` script that
+  is missing or can't be run. A mistake never stops a pipeline: the entry is
+  left out and `fun-ci why` names it as a problem.
+- `fun-ci prune` deletes the worktrees fun-ci keeps and has git forget them.
+  It refuses, and deletes nothing, while a pipeline is running.
+- `.fun-ci/console.log` notes when the console starts and stops and why it
+  stopped, what it sent every ten minutes, and when the renderer stops
+  reading or a frame takes a second or more to reach the terminal.
+- `fun-ci-renderer --colours 24bit|256` chooses the colours to draw in.
+
+### Deprecated
+- `fun-ci trigger --no-validate` is the old name for `--background`. It works
+  until 2.1 and says so on stderr.
+
+### Removed
+- The `fun-ci-trigger` and `fun-ci-tui` executables. Use `fun-ci trigger` and
+  `fun-ci console`, which have done the same job since 1.0.
+
+### Fixed
+- In a pipeline started in the background, as the post-commit hook starts
+  them (and 1.x's pre-commit hook did), the fast suite waited for the slow
+  suite to finish before it began. It now runs beside it, so the verdict a
+  push waits for comes when the fast suite is done, not the slow one.
+- A commit on a branch cancelled every unfinished run on a branch of that
+  name in every project, because all projects share one database. It now
+  cancels only its own project's runs.
+- Cancelling a stale pipeline left its stage scripts running and could let
+  the old run record itself as failed after it was cancelled. fun-ci now
+  records every process a run starts and stops all of them, and cancels runs
+  still waiting for a worktree as well. A run that had already died is only
+  marked cancelled, since the process ids it left behind may belong to
+  something else by now.
+- Cancelling a run from the console (`c`, then `y`) only marked it
+  cancelled; its stages kept running. It now stops the run.
+- A run whose fast suite failed could end up PASSED when its slow suite passed
+  afterwards, and a run showed PASSED for a moment when the slow suite
+  finished before the fast suite. A run's status now follows from all four
+  stages, whichever finishes first.
+- A slow suite whose process died without finishing left its run RUNNING for
+  ever. The console now records it failed on its next poll.
+- A database that stays busy, or can't be written because the disk is full,
+  no longer stops `fun-ci trigger`: the stages still run, the exit code is
+  theirs, and fun-ci says once that the run wasn't recorded.
+- Two fun-ci processes starting at once against a database that didn't exist
+  yet (the first commit and push on a machine, say) could die with `database
+  is locked` or `duplicate column name: project_path`. They now take turns.
+- The git hooks blocked a push when fun-ci wasn't installed, failing with
+  "fun-ci: command not found". Now they say fun-ci is missing, how to install
+  it, and let the push go ahead.
+- Git runs hooks with variables such as `GIT_INDEX_FILE` pointing at the
+  checkout. fun-ci passed them on to the git commands it runs and to your
+  stage scripts, which then read the checkout's index instead of the
+  commit's. They are cleared now.
+- `fun-ci install-hooks` wrote into `.git/hooks` even when `core.hooksPath`
+  sends git elsewhere (as husky sets it), so git never ran the hooks; and in
+  a linked worktree, whose `.git` is a file, it said the project wasn't a git
+  repository. It now asks git where the hooks go.
+- Every stage failed in a project whose path held a space, with "cannot
+  execute: No such file or directory". The stage script's path is quoted now.
+- A stage that printed without end grew fun-ci's memory without end, since
+  its output was held in memory. It is written to disk as it runs now.
+- The phase 1 line printed lint and build in whichever order they finished.
+  Lint always comes first now.
+
+## [1.2.1] - 2026-09-20
+
+### Bug Fixes
+- `StageRunner` raised `NameError: uninitialized constant FunCi::NullRecorder`
+  when built without an explicit recorder. The module reorganisation in 1.2.0
+  moved `NullRecorder` under `Persistence` and the default argument was left
+  pointing at the old name. The file also never required the recorder it names,
+  so the constant was only ever resolvable by luck of load order.
+
+### Changed
+- The gemspec reads the version from a new `lib/fun_ci/version.rb` instead of
+  loading the whole library. Loading the library pulls in sqlite3, and Bundler
+  reads the gemspec before it installs anything, so `bundle install` failed on
+  any machine that did not already happen to have sqlite3.
+- `required_ruby_version` is now `>= 3.2`. The stated floor of 3.0 was never
+  reachable: the TUI uses `Data.define`, which arrived in Ruby 3.2.
+
+### Internal
+- The cucumber suite had been broken since the 1.2.0 reorganisation, which moved
+  the files and constants it loads. It runs again, `rake` runs it, and it runs
+  with `--strict` so an undefined step fails instead of passing quietly.
+- `StageRunner` has tests. It had none, which is how the broken default survived.
+
+## [1.2.0] - 2026-02-23
+
+### Bug Fixes
+- Replaced unreliable `Timeout.timeout` with process groups (`pgroup: true`) and `Thread#join` for reliable time budget enforcement on lint/build/fast/slow stages
+- Fixed off-by-one in TUI row truncation that caused the top pipeline row to be hidden behind the header in short terminals
+- Added `Screen#height=` to clear screen on terminal height changes, preventing the header from scrolling off-screen when tmux panes resize
+- Fixed header flicker by skipping `println` when animation is active
+- Allowed null SHA on root commits so pipeline still runs
+- Detected multi-module Gradle projects from `settings.gradle`
+
+### Refactoring
+- Extracted `TerminalInput`, `KeyHandler`, `BoardRenderer` from `AdminTui` (was 257 lines/12 ivars, now 4 focused classes all under 150 lines/4 ivars)
+- Organized flat `lib/fun_ci/` into cohesive module subdirectories: `persistence/`, `pipeline/`, `setup/`, `tui/`
+
+### Internal
+- Extracted shared `ProcessRunner` module for consistent process spawning across stages
+- Updated `BackgroundWrapper` to use `[output, status, timed_out]` triples instead of exception-based timeout signaling
+- Truncated TUI board rows to fit terminal height
+
+## [1.1.0] - 2026-02-22
+
+### Added
+- Multi-line ASCII art header animations for pipeline events (explosion on failure, celebrations on success)
+- Looping idle starfield animation in the TUI header
+- Rocket animation while pipelines are running, with flickering exhaust and parallax starfield
+- HeaderAnimationManager with idle/running/event state transitions
+- AnimationLibrary with 8 animation data files (explosion, success, celebrate, flash, leprechauns, yay, idle, running)
+
+### Fixed
+- Footer animations now display 8x slower so text is actually readable
+- Animation refresh no longer blocks for 5 seconds between frames when no pipelines are running
+- Removed stale single-line header banner that conflicted with multi-line animations
+- Animation frames padded to global max width across all frames, preventing horizontal jitter
+
+## [1.0.0] - 2026-02-21
+
+### Added
+- Four-stage local CI pipeline (lint, build, fast, slow) with strict time budgets (30s/30s/10s/5min)
+- Unified CLI (`fun-ci`) with subcommands: trigger, console, init, install-hooks, check
+- Pre-commit hook (background fork, non-blocking) and pre-push hook (synchronous, blocking)
+- TUI dashboard with vim-style navigation (j/k/c/q), pagination, and project path display
+- Project scaffolding with built-in templates for Ruby (Bundler), JVM (Gradle Kotlin/Groovy, Maven)
+- SQLite persistence with WAL mode for pipeline results
+- Parallel lint + build stages with background slow suite
+- Smart Maven linter detection for template generation
+- Stale pipeline auto-cancellation

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Erik T. Madsen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,230 @@
+# Fun-CI
+
+Opinionated local CI that checks your code before it leaves your machine. Every commit runs lint, build, a fast suite and a slow suite on your own computer, each held to a strict time budget, so the feedback stays fast.
+
+![The fun-ci console following a run: a rocket while it runs, then a scene as lint, the build, the fast suite and the whole run pass](docs/screenshots/console.png)
+
+Fun-CI has two goals. It should be extremely easy to tell whether all is well, and it should be fun. The design behind both is in [docs/design.md](docs/design.md).
+
+There are two ways to use it, and both read the same results:
+
+- **You watch.** `fun-ci console` sits on a second screen. Colour and motion tell you from the corner of your eye that lint passed, the build passed, the fast suite passed, or that something failed and you should look closer. A pass gets a celebration, a failure gets an explosion.
+- **Your agent asks.** A coding agent can't glance at a screen, so it runs commands. `fun-ci wait` blocks until a commit's verdict is in and exits with it, and `fun-ci why` prints everything fun-ci kept about a failure, so the agent never has to rerun a suite to find out what broke.
+
+## Getting started
+
+```bash
+gem install fun_ci
+cd your-project
+fun-ci init --everything
+```
+
+This detects your project type, writes four stage scripts into `.fun-ci/`, installs a `post-commit` and a `pre-push` git hook, and checks the setup. It also adds a short section to your `AGENTS.md` (or `CLAUDE.md`, if that is the only one) telling coding agents what to do after a commit.
+
+`fun-ci init` has templates for Ruby, Gradle, Maven, Rust, Go, Elixir, Dart, Swift, PHP, .NET, Python, Deno, Bun, Node, Perl, and C or C++ built with CMake or make. [docs/stacks.md](docs/stacks.md) shows how it recognises each one and the commands it writes. Fun-CI works with any project: the stages are shell scripts, so edit them to run whatever your project uses.
+
+- `lint.sh`: linter and static analysis
+- `build.sh`: compile or build
+- `fast.sh`: the fast suite (unit tests)
+- `slow.sh`: the slow suite (integration tests)
+
+Each script gets the commit hash as its first argument, its stage's name in `FUN_CI_STAGE`, and exits 0 to pass.
+
+Upgrading from 1.x? Read [Upgrading to 2.0](#upgrading-to-20) first.
+
+## How a run works
+
+| Stage | Budget | Runs | Blocks |
+|-------|--------|------|--------|
+| Lint  | 30 s   | in parallel with build | the push |
+| Build | 30 s   | in parallel with lint | the push |
+| Fast  | 10 s   | after lint and build pass | the push |
+| Slow  | 5 min  | in the background, beside the fast suite | nothing |
+
+A stage that overruns its budget is killed and reported as over budget, in yellow rather than red: a fast suite that takes 12 seconds has grown too heavy, which is a different problem from a failing test.
+
+After each commit, the `post-commit` hook starts the pipeline in the background and returns at once, so a commit is never held up. The `pre-push` hook waits for the verdict of each commit you push and stops the push if lint, build or the fast suite failed. A commit whose run has already finished goes straight through. If fun-ci isn't installed, both hooks say so and let git carry on.
+
+Each run happens in a git worktree of its own under `.git/fun-ci/worktrees/`, checked out at the commit it tests, so you can keep editing while it runs. Ignored files such as `vendor/bundle` or `node_modules` stay in a worktree from one run to the next, which keeps builds quick. Two runs can go at once; set `worktree_slots: 3` in `.fun-ci/config` for more, and `fun-ci prune` removes the worktrees when you want the space back. A newer commit on a branch cancels the older run that is still going, unless an agent is waiting on it.
+
+Results are kept in SQLite under `$XDG_STATE_HOME/fun-ci/` (`~/.local/state/fun-ci/` by default), shared by every project on the machine.
+
+## Watching: the console
+
+```bash
+fun-ci console
+```
+
+The console lists your runs across branches, newest first, one row each: the commit, the branch, each stage with its time, and the outcome. Above them is a picture that tells you what is happening without reading a word.
+
+While a run runs, a rocket flies. Each milestone a run passes has its own set of scenes, so you can tell which one it was from across the room, and a failure has its own.
+
+| | |
+|---|---|
+| Lint passed: a teal sweep, a ripple or a spirit level | The build passed: amber blocks, gears or a ringing anvil |
+| ![A teal line sweeping across the header](docs/screenshots/lint-sweep.png) | ![Two amber gears turning](docs/screenshots/build-gears.png) |
+| The fast suite passed: a lightning strike, a very happy YAY or a jump to warp speed | The whole run passed: fireworks, a trophy, dancing leprechauns or a sunrise |
+| ![YAY in rainbow letters with balloons](docs/screenshots/fast-yay.png) | ![The sun rising over hills](docs/screenshots/run-sunrise.png) |
+
+Scenes queue and each plays to its end, so a failure never cuts a celebration short, and a run gets one explosion however many of its stages fail.
+
+![The console after a run's fast suite failed: an explosion reading BOOM over the runs](docs/screenshots/failure.png)
+
+When the scenes are done, the header rests on how the latest run went, so a glance a minute later still tells you: a calm tick after a pass, a pulsing hazard sign after a failure. The top right keeps count of the passes in a row.
+
+| | |
+|---|---|
+| ![A tick over a calm teal horizon](docs/screenshots/rest-passed.png) | ![A pulsing hazard triangle](docs/screenshots/rest-failed.png) |
+
+Five minutes after the latest run finished, the header goes quiet: a starry night, an aurora, fireflies, a fire in a medieval stone hearth while a storm rages at the window, a moonlit island with a lone palm, or snow falling on a pine forest, changing every five minutes while nothing runs. A small lamp in the corner stays green after a pass and flickers red after a failure.
+
+| | |
+|---|---|
+| ![A fire in a stone hearth, with a green lamp in the corner](docs/screenshots/quiet-fireplace.png) | ![A moonlit island with a palm, with a red lamp in the corner](docs/screenshots/quiet-island.png) |
+
+Keys:
+
+- `j` and `k`, or the arrow keys, move the cursor down and up
+- `c` cancels the run under the cursor: a scheduled one at once, a running one once you answer `y` (`n` or `Esc` keeps it running)
+- `q` quits
+
+The console is drawn in 24-bit colour when `COLORTERM` says the terminal has it (`truecolor` or `24bit`), and in 256 colours otherwise. The pictures above come from the renderer's headless mode, drawn with its own bitmap font; in your terminal the text is in your terminal's font.
+
+The drawing is done by a separate program, `fun-ci-renderer`, written in Rust. The gem for Linux (x86_64, aarch64, musl) and macOS (arm64, x86_64) includes it. On other Unix-like systems you get the plain gem, where every command except `console` works; install the renderer with `cargo install fun-ci-renderer` (Rust 1.88 or newer), or point `FUN_CI_RENDERER` at a copy you built. Windows is not supported, because fun-ci forks its background pipeline, but WSL runs the Linux gem. When something goes wrong between the two, the details are in `.fun-ci/console.log`.
+
+## Asking: commands for agents and scripts
+
+Every commit's output ends with the command that gets its verdict:
+
+```
+fun-ci: testing 3f9c2ab. Verdict: fun-ci wait 3f9c2ab --need all
+```
+
+The section `fun-ci init` writes into `AGENTS.md` tells an agent to run that command in the background after each commit. Agent harnesses wake the agent when a background command exits, so it hears about a failure without having to remember to ask.
+
+`status` says where a commit's run stands and `wait` blocks until it is decided. Both exit with the verdict for the stages you need: `--need build` (lint and build), `fast` (the default) or `all` (the slow suite too).
+
+| Exit code | Meaning |
+|---|---|
+| 0 | Passed |
+| 1 | A needed stage failed |
+| 2 | A needed stage ran over budget |
+| 3 | Still undecided (`wait --within 30s` gives up at your deadline) |
+| 4 | Superseded by a newer commit on the branch (`wait --follow-branch` moves on to it) |
+| 5 | No run for the commit |
+| 64 | Usage error |
+
+A failed stage comes with its evidence. `status` and `wait` end with a digest and the command that shows the rest:
+
+```
+$ fun-ci status
+fun-ci: 2330979 "Add shipping to the cart total" on main
+  lint   passed         0.6s
+  build  passed         0.3s
+  fast   FAILED         0.3s
+  slow   passed         0.5s (not needed)
+fast failed:
+    1) Failure:
+  CartTest#test_total_includes_shipping [test/cart_test.rb:16]:
+  Expected: 104.95
+    Actual: 99.95
+fun-ci why 2330979 fast
+```
+
+`why` prints how the stage ended, each failure with its whole message and its own output, what the extractors picked out of the output and the log files, and anything that went wrong collecting it. `why --raw` prints the whole output. Every command takes `--json`.
+
+```
+$ fun-ci why 2330979 fast
+fun-ci: 2330979 "Add shipping to the cart total" on main
+fast failed (exit 1) after 0.2s, budget 10s
+
+Minitest's failures and errors (output:9-12), from section:minitest:
+    1) Failure:
+  CartTest#test_total_includes_shipping [test/cart_test.rb:16]:
+  Expected: 104.95
+    Actual: 99.95
+
+The output's last lines, from output-tail:
+  Run options: --seed 20502
+  ...
+  3 runs, 3 assertions, 1 failures, 0 errors, 0 skips
+  rake aborted!
+  Command failed with status (1)
+  ...
+
+The whole output: fun-ci why 2330979 fast --raw
+```
+
+`fun-ci runs` lists recent runs one line each, and `fun-ci events --follow` prints each run's events as JSON lines as they happen, for a supervising agent or a status bar.
+
+### What fun-ci keeps when a stage fails
+
+With no configuration, fun-ci runs the presets for the tools your project has when a failure shows them. There are presets for the test runners, compilers, linters and type checkers of every stack `fun-ci init` knows, and for JSON logs from logstash-logback-encoder, ECS, pino and structlog; [docs/stacks.md](docs/stacks.md#presets) lists each one with what it picks out and when it runs. Each preset is checked against the recorded output of a real failing run of its tool. `fun-ci check` lists the ones that apply to your project.
+
+To keep more, add entries under `evidence:` in `.fun-ci/config`:
+
+```yaml
+evidence:
+  stages:
+    fast:
+      - use: junit-files         # each failure in the JUnit XML the stage wrote,
+        paths: [build/test-results/test/*.xml]   # as file, line, test and message
+      - use: log-file            # what the stage wrote to it, and only that
+        path: log/test.log
+        grep: ["ERROR"]
+        context: 5
+    slow:
+      - run: .fun-ci/evidence/problems   # your own extractor, in any language:
+        format: json                     # the context on stdin, JSON on stdout
+      - run: pkill -QUIT -g "$FUN_CI_PGID" java   # a thread dump before an overrun is killed
+        on: overrun
+```
+
+`fun-ci extract fast --output saved.log` runs a stage's extractors against a saved output (`fun-ci why --raw > saved.log`), so you can try an entry without making a commit. A mistake under `evidence:` never stops a pipeline: `fun-ci check` reports it and `fun-ci why` names it.
+
+Secrets in the stage's environment are masked before anything is kept: the value of any variable whose name holds TOKEN, SECRET, PASSWORD, PASSWD, API_KEY, PRIVATE_KEY or CREDENTIAL, and GitHub, AWS and Slack tokens, private keys and `Authorization:` headers wherever they appear. The state directory is readable by your user alone.
+
+## Commands
+
+```
+fun-ci init                                     Scaffold .fun-ci/ for the detected project type
+fun-ci init --everything                        init + install-hooks + check in one step
+fun-ci install-hooks                            Install post-commit and pre-push hooks
+fun-ci install-hooks post-commit                Install a single hook type
+fun-ci check                                    Verify .fun-ci/ setup
+fun-ci console                                  Watch the runs
+fun-ci status [commit]                          Where a commit's run stands; the verdict is the exit code
+fun-ci wait [commit]                            Wait until that verdict is decided, then exit with it
+fun-ci why [commit] [stage]                     Everything kept about why a stage failed
+fun-ci runs                                     This project's recent runs, newest first
+fun-ci events [--follow]                        The runs' events as JSON lines
+fun-ci extract <stage> --output <file>          Try a stage's extractors on a saved output
+fun-ci trigger <commit> <branch>                Run the whole pipeline in the foreground
+fun-ci trigger --background <commit> <branch>   Start the pipeline in the background (what post-commit runs)
+fun-ci prune                                    Remove fun-ci's worktrees when no pipeline is running
+```
+
+`fun-ci --help` lists every option.
+
+## Upgrading to 2.0
+
+- Run `fun-ci install-hooks` again. The background pipeline now runs after the commit (`post-commit`), so it tests the commit you just made; the `pre-commit` hook tested the one before it. Until you do, each run tests the commit before yours, and `fun-ci check` warns you. Installing removes the `pre-commit` hook fun-ci 1.x wrote and leaves a hook of your own alone (`fun-ci check` warns if yours still calls fun-ci). The new `pre-push` hook waits for the verdict instead of running the pipeline again.
+- The stages run in a worktree at the commit, not in your checkout. A script that relied on uncommitted files in your checkout won't see them any more.
+- The database moved from `$TMPDIR` to `$XDG_STATE_HOME/fun-ci/`. Runs recorded by 1.x are not carried over.
+- `fun-ci-trigger` and `fun-ci-tui` are gone; use `fun-ci trigger` and `fun-ci console`. `fun-ci trigger --no-validate` still works until 2.1, as the old name for `--background`.
+- The console needs `fun-ci-renderer`, which the platform gems include (see [Watching: the console](#watching-the-console)).
+
+The whole list is in [CHANGELOG.md](CHANGELOG.md).
+
+## Development
+
+```bash
+bundle install
+bundle exec rake   # the gate: tests, the renderer's tests, the binary contract, rubocop, clippy
+```
+
+How it is built is in [docs/architecture.md](docs/architecture.md), and the requirements are in [docs/acceptance-tests.md](docs/acceptance-tests.md). The renderer is written in Rust; install Rust with [rustup](https://rustup.rs), which picks up the version the repository pins in `rust-toolchain.toml`. `ruby script/readme_screenshots.rb` draws the pictures in this README again.
+
+## License
+
+MIT

data/exe/fun-ci

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/fun_ci"
+require_relative "../lib/fun_ci/cli"
+
+exit FunCi::Cli.run(ARGV)

data/lib/fun_ci/agent/age.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module FunCi
+  module Agent
+    # How long ago something happened, in the largest whole unit.
+    module Age
+      UNITS = [[86_400, "d"], [3600, "h"], [60, "m"]].freeze
+
+      def self.words(seconds)
+        size, unit = UNITS.find { |unit_seconds, _| seconds >= unit_seconds }
+        size ? "#{(seconds / size).floor}#{unit} ago" : "just now"
+      end
+    end
+  end
+end

data/lib/fun_ci/agent/command_support.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "options"
+require_relative "reports"
+require_relative "exit_code"
+
+module FunCi
+  module Agent
+    # What the agent commands share: the commit a revision names, the reports
+    # of its runs, and refusing arguments they can't use. Expects @context and
+    # a NAME constant.
+    module CommandSupport
+      private
+
+      def resolve(rev)
+        @context.git.resolve(rev) || raise(Options::Invalid, "git can't find the commit '#{rev}'")
+      end
+
+      def reports = @reports ||= Reports.new(@context.db, @context.git)
+
+      def usage(message)
+        @context.io.stderr.puts "fun-ci #{self.class::NAME}: #{message}"
+        ExitCode::USAGE
+      end
+    end
+  end
+end

data/lib/fun_ci/agent/commands.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "../pipeline/trigger_params"
+require_relative "context"
+require_relative "git"
+require_relative "system_clock"
+require_relative "live_pipeline"
+require_relative "status_command"
+require_relative "runs_command"
+require_relative "wait_command"
+require_relative "events_command"
+require_relative "why_command"
+
+module FunCi
+  module Agent
+    # The commands an agent runs in a project, each answered from the
+    # database and the project's git.
+    module Commands
+      ALL = { "status" => StatusCommand, "runs" => RunsCommand, "wait" => WaitCommand,
+              "events" => EventsCommand, "why" => WhyCommand }.freeze
+
+      def self.run(name, args, context)
+        ALL.fetch(name).new(context).run(args)
+      end
+    end
+  end
+end

data/lib/fun_ci/agent/context.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module FunCi
+  module Agent
+    # What every agent command answers from: the database, the project's git,
+    # where to print, the time (#now, #pause) and the pipeline (#start a run,
+    # #watch the database for slow suites that died).
+    Context = Data.define(:db, :git, :io, :clock, :pipeline)
+  end
+end