Chapter 05: Fast Feedback and Automatic Shells

Objective

Use targeted tasks for fast feedback and configure direnv with an explicit trust boundary.

Your tutor should stop at each gate and wait for your evidence before continuing.

Concept

Different feedback has different costs. A formatter is quick; a database test needs a running service. Expose both through a small vocabulary so an agent can iterate cheaply and still finish with full validation.

Our check:all task depends on format, lint, and unit tasks. Those tasks only read files, so they can safely run concurrently. A formatter that rewrites files must not race with tests reading them. A database integration task also needs readiness and cleanup; simply naming it check:integration does not start PostgreSQL.

direnv automates entering an environment when you change directories. Its approval is a trust decision: .envrc is executable shell code. It belongs outside the project’s self-bootstrapping paradox—the tool must be available in your ordinary shell before it can activate the project.

Concept check

Q1. Why is ruff format --check suitable for a parallel check graph, while ruff format needs care?

Q2. Does adding direnv to project packages install your ordinary shell’s direnv hook?

Gate: Run targeted tasks

devenv tasks run check:unit
devenv tasks run check:all
devenv test

Pass: the unit task runs the suite, the aggregate includes all three declared checks, and the final command also runs the database contract after Chapter 04. Compare elapsed times. Tasks use after to name prerequisites; consult the task documentation before changing execution modes.

Optional advanced wiring can attach tasks before devenv:enterTest. The lab keeps enterTest explicit so service lifecycle and the final gate remain easy to audit.

Current devenv also offers native auto activation through devenv hook; the upstream guide recommends that route for many workflows. This lesson uses the still-supported direnv integration to make its explicit approval boundary visible. Choose one activation mechanism.

Gate: Install and verify direnv

nix profile install nixpkgs#direnv
direnv version

For zsh on the Mac, add the following once to ~/.zshrc:

eval "$(direnv hook zsh)"

For Bash, use the Bash hook in the appropriate interactive startup file. Open a new terminal and verify direnv version before creating .envrc.

Gate: Review the integration

Use the .envrc generated by your installed devenv, if present. Otherwise create this documented integration:

watch_file devenv.nix
watch_file devenv.yaml
watch_file devenv.lock
eval "$(devenv direnvrc)"
use devenv

Read it and the referenced project files, then run:

direnv allow
python -c 'import sys; print(sys.executable)'

Pass: the project Python is selected when entering the directory. Leave the directory and verify that direnv unloads its changes. A tool may still exist outside the project if it was installed independently; unloading does not uninstall it.

Gate: Change a dependency deliberately

Add pkgs.tree to the package list. Re-enter or reload the shell, run tree --version, review the Nix diff, and commit it. No agent should repair an undeclared project dependency by silently changing your host.

Known failure modes

• .envrc is not automatically trustworthy because it is in Git.
• A task named check:all can omit integration tests; the documented final gate remains devenv test.
• Modified-file caching can hide environment-dependent failures. Keep acceptance checks uncached until their inputs are well defined.
• Auto activation can be convenient for a human; CI should invoke commands explicitly.

Check your understanding

Q3. What is the final gate after a targeted test passes?

Q4. What should you inspect before approving an unfamiliar .envrc?

References

• Tasks and dependencies
• direnv integration
• direnv shell hooks

← Chapter 04 · Next: Chapter 06 →