From 33278d9ed2fc9b30c1bcbd8879343096d30e7e4c Mon Sep 17 00:00:00 2001 From: Emma Thorpe Date: Fri, 10 Jul 2026 11:25:56 +0100 Subject: [PATCH 1/2] docs: add project CLAUDE.md documenting flake checks Document the formatting and lint gates (treefmt/nixfmt/shfmt/prettier, deadnix, statix, pre-commit) and how to run them, so changes -- docs included -- are formatted before commit. Notes the CI detect step that skips heavy checks on docs-only PRs, which can report a false green. Co-Authored-By: Claude Opus 4.8 (1M context) --- CLAUDE.md | 63 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 63 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..564a913 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,63 @@ +# Working on this flake + +Project notes for changes to this repository. Persona and memory rules live in +the user-global config; this file is about the flake's checks and conventions. + +## Before you commit: run the formatter + +Formatting and linting are driven by the flake. CI (`.gitea/workflows/ci.yaml`) +runs `nix flake check`, which fails the build if any file is unformatted or trips +a lint. From the repo root: + +- `nix fmt` — format the whole tree (writes changes). +- `nix flake check` — run every check read-only (what CI runs). +- `nix develop` — dev shell; its `shellHook` installs the git pre-commit hooks so + the same gates run on `git commit`. + +Never commit with `--no-verify`. A bypassed commit ships unformatted content and +turns CI red on the next push to `main` (see "Docs are checked too"). + +## What gets checked + +Defined in `flake.nix` (the `treefmt`, `pre-commit`, and `checks` blocks) and +`statix.toml`: + +| Check | Tool | Covers | +| ------------ | --------------------------------- | ------------------------------------------------------- | +| `formatting` | treefmt → `nixfmt` | all `*.nix` | +| `formatting` | treefmt → `shfmt` | shell scripts | +| `formatting` | treefmt → `prettier` | **Markdown, YAML, JSON** (incl. `README.md`, this file) | +| `deadnix` | deadnix | dead Nix bindings (`--no-lambda-pattern-names`) | +| `statix` | statix | Nix antipatterns (config in `statix.toml`) | +| pre-commit | nixfmt-rfc-style, deadnix, statix | the same gates, run on commit | + +Excluded from formatting: `*/hardware-configuration.nix` (generated by +`nixos-generate-config`) and `flake.lock`. Editor defaults (indent, EOL, final +newline) are in `.editorconfig`; note Markdown keeps trailing whitespace, which +encodes hard line breaks. + +## Docs are checked too — the common trap + +prettier formats `*.md`, so **documentation edits must be run through `nix fmt`** +exactly like code. prettier re-aligns Markdown tables in particular; hand-editing +a table almost always leaves it non-conformant and fails the `formatting` check. + +Beware a false green: the CI `detect` step skips the heavy checks on a pull +request that touches **no** `.nix`, `flake.lock`, or the workflow file — so a +docs-only PR reports success without ever running prettier. The failure then +surfaces on the push-to-`main` run (which always runs the full check) or on the +next unrelated PR that does touch Nix. Run `nix flake check` locally before +merging a docs change, regardless of what the PR check shows. + +## Host evaluation + +CI also evaluates every `nixosConfigurations` / `darwinConfigurations` host's +toplevel (eval only, no build) on an x86_64 runner, so eval errors fail cheaply. +Reproduce locally: + +```sh +nix eval --raw ".#nixosConfigurations..config.system.build.toplevel.drvPath" +``` + +Host lists are discovered from the flake, so adding or removing a host needs no +change to the workflow. -- 2.54.0 From 9b7a9fa9b939a511ed9a4d5f3311a7310759886d Mon Sep 17 00:00:00 2001 From: Emma Thorpe Date: Fri, 10 Jul 2026 11:25:56 +0100 Subject: [PATCH 2/2] chore(memory): note nix shell for ad-hoc nixpkgs tooling Record that any nixpkgs tool can be run on the fly via nix run / nix shell, so a missing command during development is not a dead end. Takes effect after a home-manager rebuild. Co-Authored-By: Claude Opus 4.8 (1M context) --- home/claude/memory/MEMORY.md | 1 + home/claude/memory/nix_shell_tooling.md | 23 +++++++++++++++++++++++ 2 files changed, 24 insertions(+) create mode 100644 home/claude/memory/nix_shell_tooling.md diff --git a/home/claude/memory/MEMORY.md b/home/claude/memory/MEMORY.md index 3210df4..aae31cf 100644 --- a/home/claude/memory/MEMORY.md +++ b/home/claude/memory/MEMORY.md @@ -9,3 +9,4 @@ - [Review and comments workflow](workflow_review_and_comments.md) — show PR body and non-trivial Jira comments before posting; terse IaC code comments; PR body content rules - [Sandbox prompts](feedback_sandbox_prompts.md) — don't prompt for sandbox-disable or routine read-only shell ops; broaden permissions instead - [Dev clusters disposable](dev_clusters_disposable.md) — Lyra's dev clusters are recreatable; mutate/break freely, no confirmation needed +- [Nix shell tooling](nix_shell_tooling.md) — any nixpkgs tool runs ad hoc via `nix run`/`nix shell nixpkgs#`; a missing command is never a dead end diff --git a/home/claude/memory/nix_shell_tooling.md b/home/claude/memory/nix_shell_tooling.md new file mode 100644 index 0000000..132e4e8 --- /dev/null +++ b/home/claude/memory/nix_shell_tooling.md @@ -0,0 +1,23 @@ +--- +name: nix-shell-tooling +description: "Any nixpkgs tool can be run ad hoc via nix run / nix shell — a missing command is never a dead end during development" +metadata: + node_type: memory + type: feedback + originSessionId: dfb56b58-518b-4daf-b531-7119bb4a9534 +--- + +Any tool in nixpkgs can be run without installing it into the environment. If a +command is missing during development, pull it from nixpkgs on the fly instead +of working around its absence or reporting the tool as unavailable. + +**Why:** Lyra runs NixOS; the ambient PATH is deliberately minimal, but the full +nixpkgs set is always one command away. "command not found" is not a blocker. + +**How to apply:** + +- One-off run: `nix run nixpkgs# -- ` (e.g. `nix run nixpkgs#jq -- .`). +- Tools on PATH for a session: `nix shell nixpkgs# [nixpkgs# ...]`, + then run commands normally. +- Legacy form also works: `nix-shell -p --run ''`. +- Prefer this over hand-rolling a substitute for a tool that exists in nixpkgs. -- 2.54.0