From 765d7259487eecb3f843c2541140809064ac3eff Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 31 Oct 2026 11:23:20 +0000 Subject: [PATCH] Converge on the org flake standard - Inputs: org-pkgs; nixpkgs (was nixos-26.05), flake-parts and import-tree follow it. mkdocs-flake and reveal-js stay at the root: the exports need them. - Dev partition with its own inputs (dev/flake.nix, dev/flake.lock: dev-nixpkgs, treefmt-nix) importing org-pkgs flakeModules.dev: checks.treefmt replaces the lint check and pkgs.alejandra formatter; adds lock-sync and sync-locks. This repo's docs and deck move into the partition (documentation/flake-module.nix imports self.flakeModules.default), exposed as legacyPackages so `nix build .#documentation` still works. - Drop the flake devShell; devenv CLI shell (org-pkgs/devenv). - slides/ moves to documentation/slides; mkdocs.yml gets the org settings (dev_addr 8981, use_directory_urls false, offline). - systems: x86_64-linux and aarch64-linux. debug = true and .vscode nixd settings. AGENTS.md; README and docs updated. lib, flakeModules and templates are unchanged. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01E5NrkgRkUQCo4RecQu5LUr --- .gitignore | 4 + .vscode/extensions.json | 3 + .vscode/settings.json | 25 +++ AGENTS.md | 27 +++ README.md | 23 ++- dev/flake-module.nix | 9 + dev/flake.lock | 48 +++++ dev/flake.nix | 18 ++ devenv.lock | 106 +++++++++++ devenv.nix | 3 + devenv.yaml | 15 ++ documentation/docs/getting-started.md | 13 +- documentation/docs/index.md | 2 +- documentation/docs/nix.md | 36 ++-- documentation/docs/presentation.md | 6 +- documentation/docs/reveal-js.md | 12 +- documentation/flake-module.nix | 22 +++ documentation/mkdocs.yml | 10 + {slides => documentation/slides}/index.html | 0 {slides => documentation/slides}/slides.md | 0 flake-parts/checks.nix | 36 ---- flake-parts/default.nix | 20 -- flake.lock | 191 ++++++++++++-------- flake.nix | 66 ++++--- 24 files changed, 498 insertions(+), 197 deletions(-) create mode 100644 .vscode/extensions.json create mode 100644 .vscode/settings.json create mode 100644 AGENTS.md create mode 100644 dev/flake-module.nix create mode 100644 dev/flake.lock create mode 100644 dev/flake.nix create mode 100644 devenv.lock create mode 100644 devenv.nix create mode 100644 devenv.yaml create mode 100644 documentation/flake-module.nix rename {slides => documentation/slides}/index.html (100%) rename {slides => documentation/slides}/slides.md (100%) delete mode 100644 flake-parts/checks.nix delete mode 100644 flake-parts/default.nix diff --git a/.gitignore b/.gitignore index a3b693f..3697b76 100644 --- a/.gitignore +++ b/.gitignore @@ -2,5 +2,9 @@ result result-* +# devenv +.devenv* +devenv.local.nix + # `mkdocs build` output, if you ever run mkdocs outside Nix documentation/site/ diff --git a/.vscode/extensions.json b/.vscode/extensions.json new file mode 100644 index 0000000..0b04a3b --- /dev/null +++ b/.vscode/extensions.json @@ -0,0 +1,3 @@ +{ + "recommendations": ["jnoortheen.nix-ide"] +} diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000..a59c1b3 --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,25 @@ +{ + "nix.enableLanguageServer": true, + "nix.serverPath": "nixd", + "nix.serverSettings": { + "nixd": { + "nixpkgs": { + "expr": "import (builtins.getFlake (builtins.toString ./.)).inputs.nixpkgs { }" + }, + "formatting": { + "command": ["alejandra", "--quiet"] + }, + "options": { + "flake-parts": { + "expr": "(builtins.getFlake (builtins.toString ./.)).debug.options" + }, + "flake-parts-perSystem": { + "expr": "(builtins.getFlake (builtins.toString ./.)).currentSystem.options" + }, + "nixos": { + "expr": "((builtins.getFlake (builtins.toString ./.)).inputs.nixpkgs.lib.nixosSystem { modules = [ { nixpkgs.hostPlatform = builtins.currentSystem; } ]; }).options" + } + } + } + } +} diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..5fe5e7d --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,27 @@ +# AGENTS.md + +MkDocs docs site + reveal.js slide deck tooling for external-systems +flakes. Consumers import `flakeModules.default` (docs + slides) or +`flakeModules.slides`, or call `lib.mkSlides`; `templates.default` is +this whole repo. The reveal.js pin travels with those exports. This repo +builds its own docs and deck with the same module. + +## Layout +- `flake.nix`: consumer-facing inputs (org-pkgs; mkdocs-flake, reveal-js) and exports (lib, flakeModules), plus the dev partition wiring. +- `lib/default.nix`: `mkSlides`. `flakeModules/slides.nix`: the `presenting.slides.*` module. +- `flake-parts/`: consumer-facing modules, auto-imported (import-tree): `template.nix`. `flake-parts/scripts/inline-markdown.py` is used by `mkSlides`. +- `dev/flake.nix` + `dev/flake.lock`: dev-only inputs. `dev/flake-module.nix`: the dev partition (formatter, checks, this repo's docs and deck). +- `devenv.yaml` + `devenv.lock` + `devenv.nix`: the dev shell. The org shell comes from external-systems/pkgs (`org-pkgs/devenv` in devenv.yaml). +- `documentation/`: `flake-module.nix`, MkDocs site (`mkdocs.yml`, `docs/`) and reveal.js deck (`slides/`). + +## Tool loop +- The shell is devenv. If `DEVENV_ROOT` is unset, run commands with `devenv shell -- `. +- `git add` new files before any `nix` command. +- `fmt`, then `check`. Both must pass before a change is done. +- After `nix flake update org-pkgs`, run `sync-locks` in the same commit. + +## Rules +- Load the `nix-style` skill before editing any `.nix` file, and `mkdocs-reveal` before changing the exports. +- Dev-only inputs go in `dev/flake.nix`, never `flake.nix`. +- Never change the shape of `lib`, `flakeModules` or `templates` without updating every consumer (pkgs template, skills, secrets, not-secrets, modules, home, clanServices). +- Work on a branch and open a PR. Never push to `main`. diff --git a/README.md b/README.md index f630d86..cbb3a71 100644 --- a/README.md +++ b/README.md @@ -12,15 +12,17 @@ reveal.js + MkDocs, built by a Nix flake. Two ways to use it: A static documentation website ([MkDocs](https://www.mkdocs.org) + [Material](https://squidfunk.github.io/mkdocs-material/)) and a slide deck ([reveal.js](https://revealjs.com)), both built by a Nix flake. No Python, -Node or npm to install, only Nix. +Node or npm to install, only Nix (and devenv for the dev shell). ```bash -nix run .#watch-documentation # live docs preview → http://127.0.0.1:8000 -nix run .#serve-slides # live slides preview → http://127.0.0.1:8000 +devenv allow # auto-activates the shell on cd (after `devenv hook`) +fmt # nix fmt: treefmt with the org linters +check # nix flake check: lint, lock sync, both builds +docs-build # static docs to ./result-docs; open index.html from disk +devenv up # live docs on :8981 and slides on :8982 nix build .#documentation # ./result = docs website nix build .#slides # ./result = slide deck -nix flake check # build both + lint the Nix code ``` Remember to `git add` new files: Nix only sees files git tracks. @@ -65,11 +67,16 @@ present — the embed via `documentation.mkdocs-preBuildHook` call the builder directly: `inputs.presenting.lib.mkSlides { inherit pkgs; slidesDir = ./slides; }`. ```text -flake.nix inputs + exports (lib, flakeModules, template), locked in flake.lock +flake.nix inputs (follow external-systems/pkgs) + exports (lib, flakeModules, template) lib/ mkSlides: the root-agnostic deck builder other flakes reuse flakeModules/ the exportable flake-parts module (presenting.slides.* options) -flake-parts/ this repo's own config, auto-imported: docs settings, checks +flake-parts/ consumer-facing modules, auto-imported: the template output +dev/ dev partition: inputs (dev/flake.lock), formatter, checks, docs +devenv.yaml dev shell (devenv CLI), the org shell from external-systems/pkgs +documentation/ flake-module.nix + MkDocs site (mkdocs.yml, docs/) + slides/ deck .github/workflows/ pages.yml: check, build and deploy the docs site to GitHub Pages -documentation/ MkDocs site: mkdocs.yml + docs/*.md -slides/ reveal.js deck: index.html + slides.md +.vscode/ nixd (Nix language server) settings ``` + +The repo follows the org flake standard (nix-style skill): after +`nix flake update org-pkgs`, run `sync-locks` in the same commit. diff --git a/dev/flake-module.nix b/dev/flake-module.nix new file mode 100644 index 0000000..efd84b3 --- /dev/null +++ b/dev/flake-module.nix @@ -0,0 +1,9 @@ +# Dev partition: the org base (treefmt, lock-sync, docs and slides as +# checks) from pkgs, and this repo's own docs site and deck. A consumer +# of lib, flakeModules or templates never evaluates it. +{inputs, ...}: { + imports = [ + inputs.org-pkgs.flakeModules.dev + ../documentation/flake-module.nix + ]; +} diff --git a/dev/flake.lock b/dev/flake.lock new file mode 100644 index 0000000..e09c9e5 --- /dev/null +++ b/dev/flake.lock @@ -0,0 +1,48 @@ +{ + "nodes": { + "dev-nixpkgs": { + "locked": { + "lastModified": 1793110635, + "narHash": "sha256-dhoW6VgFWlaodSY5jrBn+CF2FLmaUvDVgM7+C7T2+NM=", + "owner": "NixOS", + "repo": "nixpkgs", + "rev": "31ecbaca1bdefa45dffc409f0250bd8039ea0010", + "type": "github" + }, + "original": { + "owner": "NixOS", + "ref": "nixos-unstable", + "repo": "nixpkgs", + "type": "github" + } + }, + "treefmt-nix": { + "inputs": { + "nixpkgs": [ + "dev-nixpkgs" + ] + }, + "locked": { + "lastModified": 1791885023, + "narHash": "sha256-C3alQ2MEt0zVrUSho5NUDo3jmhbff72++bfwoqT9Omo=", + "owner": "numtide", + "repo": "treefmt-nix", + "rev": "0d6d739a833ba9a9c93034862e4a7b061a062a1c", + "type": "github" + }, + "original": { + "owner": "numtide", + "repo": "treefmt-nix", + "type": "github" + } + }, + "root": { + "inputs": { + "dev-nixpkgs": "dev-nixpkgs", + "treefmt-nix": "treefmt-nix" + } + } + }, + "root": "root", + "version": 7 +} diff --git a/dev/flake.nix b/dev/flake.nix new file mode 100644 index 0000000..83b871e --- /dev/null +++ b/dev/flake.nix @@ -0,0 +1,18 @@ +{ + description = "Development-only inputs for presenting (the dev partition)"; + + # Locked in dev/flake.lock, never in the main flake.lock. dev-nixpkgs + # must lock the same rev as the root nixpkgs (checks.lock-sync; fix + # with `sync-locks`). No `presenting` input: this repo's docs use its + # own flakeModules (documentation/flake-module.nix). + inputs = { + dev-nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable"; + + treefmt-nix = { + url = "github:numtide/treefmt-nix"; + inputs.nixpkgs.follows = "dev-nixpkgs"; + }; + }; + + outputs = _: {}; +} diff --git a/devenv.lock b/devenv.lock new file mode 100644 index 0000000..9379ced --- /dev/null +++ b/devenv.lock @@ -0,0 +1,106 @@ +{ + "nodes": { + "devenv": { + "locked": { + "dir": "src/modules", + "lastModified": 1793199252, + "narHash": "sha256-LRgdAdMHL3uIX+kix/oyMzG+gMxzSYOzLrrRaoZthog=", + "owner": "cachix", + "repo": "devenv", + "rev": "0d6c556e5f862c14a75a543e2ee4fdb7acc005ad", + "type": "github" + }, + "original": { + "dir": "src/modules", + "owner": "cachix", + "repo": "devenv", + "type": "github" + } + }, + "flake-parts": { + "inputs": { + "nixpkgs-lib": [ + "org-pkgs", + "nixpkgs" + ] + }, + "locked": { + "lastModified": 1790898470, + "narHash": "sha256-zTwuwezD0w3hpga6a6P8emidzAZFyWqlNeRBlpWOOl8=", + "owner": "hercules-ci", + "repo": "flake-parts", + "rev": "024633cd702b10285db5cb19b40ad48d2399ba60", + "type": "github" + }, + "original": { + "owner": "hercules-ci", + "repo": "flake-parts", + "type": "github" + } + }, + "import-tree": { + "locked": { + "lastModified": 1788467110, + "narHash": "sha256-ljEMTXP/rH0tOvDzc9gzwww6KcHRPRnEHzd9lK48V7s=", + "owner": "denful", + "repo": "import-tree", + "rev": "eb1b52eaecc57f7c136d07ae8a93e724dfecac46", + "type": "github" + }, + "original": { + "owner": "denful", + "repo": "import-tree", + "type": "github" + } + }, + "nixpkgs": { + "locked": { + "lastModified": 1793110635, + "narHash": "sha256-dhoW6VgFWlaodSY5jrBn+CF2FLmaUvDVgM7+C7T2+NM=", + "owner": "NixOS", + "repo": "nixpkgs", + "rev": "31ecbaca1bdefa45dffc409f0250bd8039ea0010", + "type": "github" + }, + "original": { + "owner": "NixOS", + "ref": "nixos-unstable", + "repo": "nixpkgs", + "type": "github" + } + }, + "org-pkgs": { + "inputs": { + "flake-parts": "flake-parts", + "import-tree": "import-tree", + "nixpkgs": "nixpkgs" + }, + "locked": { + "lastModified": 1793444658, + "narHash": "sha256-Fk+uJAmFS0FbZqH48EoqRifwiJM1Z1TlfX5f4hZS4/M=", + "owner": "external-systems", + "repo": "pkgs", + "rev": "e058d99fe9f04de4fc47ce892d0efbfebba7929b", + "type": "github" + }, + "original": { + "owner": "external-systems", + "repo": "pkgs", + "rev": "e058d99fe9f04de4fc47ce892d0efbfebba7929b", + "type": "github" + } + }, + "root": { + "inputs": { + "devenv": "devenv", + "nixpkgs": [ + "org-pkgs", + "nixpkgs" + ], + "org-pkgs": "org-pkgs" + } + } + }, + "root": "root", + "version": 7 +} \ No newline at end of file diff --git a/devenv.nix b/devenv.nix new file mode 100644 index 0000000..1e56969 --- /dev/null +++ b/devenv.nix @@ -0,0 +1,3 @@ +# presenting's additions to the org shell (org-pkgs/devenv): none yet. +# Languages, services and app processes go here. +_: {} diff --git a/devenv.yaml b/devenv.yaml new file mode 100644 index 0000000..07036ce --- /dev/null +++ b/devenv.yaml @@ -0,0 +1,15 @@ +# devenv CLI entry: devenv shell, auto-activation (devenv hook + devenv +# allow), devenv up, devenv test, devenv mcp. nixpkgs comes from pkgs at +# the rev flake.lock holds (checks.lock-sync; fix with `sync-locks`). +# The input is NOT named `pkgs`: devenv passes every input to devenv.nix +# as a module argument, so an input called `pkgs` would replace nixpkgs' +# pkgs ("attribute 'bash' missing"). +inputs: + org-pkgs: + url: github:external-systems/pkgs/e058d99fe9f04de4fc47ce892d0efbfebba7929b + nixpkgs: + follows: org-pkgs/nixpkgs +imports: + # The org shell: fmt, check, sync-locks, docs, slides; devenv up serves + # docs and slides. + - org-pkgs/devenv diff --git a/documentation/docs/getting-started.md b/documentation/docs/getting-started.md index 7ebbc33..cc3984b 100644 --- a/documentation/docs/getting-started.md +++ b/documentation/docs/getting-started.md @@ -44,12 +44,13 @@ Each command starts a small web server. Leave it running, edit files, and refresh the browser. ```bash -nix run .#watch-documentation # docs → http://127.0.0.1:8000 (auto-reloads) -nix run .#serve-slides # slides → http://127.0.0.1:8000 (refresh by hand) +nix run .#watch-documentation # docs → http://127.0.0.1:8981 (auto-reloads) +nix run .#serve-slides -- 8982 # slides → http://127.0.0.1:8982 (refresh by hand) ``` -Both use port 8000, so run one at a time, or give the slides another -port: `nix run .#serve-slides -- 8001`. +Or run both at once in the devenv shell: `devenv up`. The docs port is +`dev_addr` in `documentation/mkdocs.yml`; the slides take the port as an +argument (default 8000). The first run downloads and builds the tools, which takes a few minutes. Later runs start in seconds. @@ -73,8 +74,8 @@ nix build .#documentation .#slides ## 5. Check everything before you push ```bash -nix fmt . # format the .nix files -nix flake check # builds both sites and lints the Nix code +nix fmt # format and lint (treefmt) +nix flake check # builds both sites, lints, checks the lock files ``` ## 6. Publish to GitHub Pages diff --git a/documentation/docs/index.md b/documentation/docs/index.md index 6f66b82..1d353ad 100644 --- a/documentation/docs/index.md +++ b/documentation/docs/index.md @@ -5,7 +5,7 @@ This repository builds **two static websites** from plain text files: | What | Source | Built with | Build command | | --- | --- | --- | --- | | This documentation site | `documentation/` | [MkDocs](https://www.mkdocs.org) + [Material](https://squidfunk.github.io/mkdocs-material/) | `nix build .#documentation` | -| A slide deck | `slides/` | [reveal.js](https://revealjs.com) | `nix build .#slides` | +| A slide deck | `documentation/slides/` | [reveal.js](https://revealjs.com) | `nix build .#slides` | Both builds produce a folder of HTML, CSS and JavaScript (`./result`) that any static host can serve: GitHub Pages, Cloudflare Pages, Netlify, an S3 diff --git a/documentation/docs/nix.md b/documentation/docs/nix.md index 2b68703..ff4a0d5 100644 --- a/documentation/docs/nix.md +++ b/documentation/docs/nix.md @@ -13,18 +13,24 @@ lib/ flakeModules/ └── slides.nix # the exportable flake-parts module (presenting.slides.* options) flake-parts/ -├── default.nix # formatter + MkDocs settings + presenting.slides.dir ├── scripts/ │ └── inline-markdown.py # folds slides.md into index.html at build time -├── checks.nix # `nix flake check`: both builds + the Nix linters └── template.nix # lets `nix flake init -t` copy this repo (delete it in your copy if you like) -documentation/ # the MkDocs site -slides/ # the reveal.js deck +dev/ +├── flake.nix # dev-only inputs (treefmt-nix), locked in dev/flake.lock +└── flake-module.nix # the dev partition: formatter, checks, this repo's docs + deck +devenv.yaml # the dev shell (devenv CLI): the org shell from external-systems/pkgs +documentation/ +├── flake-module.nix # MkDocs settings + presenting.slides.dir +├── mkdocs.yml, docs/ # the MkDocs site +└── slides/ # the reveal.js deck ``` This repo builds its own deck with the same module it exports — what you get from `inputs.presenting.flakeModules.slides` is exactly what builds -`slides/` here. +`documentation/slides/` here. The docs and deck live in the flake's `dev` +[partition](https://flake.parts/options/flake-parts-partitions.html), so +a consumer of the exports never fetches this repo's dev inputs. ## Inputs and the lock file @@ -32,7 +38,8 @@ get from `inputs.presenting.flakeModules.slides` is exactly what builds | Input | What it is | | --- | --- | -| `nixpkgs` | the Nix package collection (Python, alejandra, ...) | +| `org-pkgs` | external-systems/pkgs: the org's pins; `nixpkgs`, `flake-parts` and `import-tree` follow it | +| `nixpkgs` | the Nix package collection (Python, ...) | | `flake-parts` | splits the flake into small modules | | `import-tree` | loads every file in `flake-parts/` automatically | | `mkdocs-flake` | MkDocs + Material + plugins, as a flake-parts module | @@ -42,8 +49,9 @@ get from `inputs.presenting.flakeModules.slides` is exactly what builds it: it is what makes the build reproducible. ```bash -nix flake update # move every input to its newest version -nix flake update reveal-js # update just one +nix flake update reveal-js # update one input +nix flake update org-pkgs # move the org pins (nixpkgs, ...), then: +sync-locks # re-pin dev/flake.lock and devenv.lock to the same nixpkgs nix flake metadata # show what is locked ``` @@ -76,9 +84,9 @@ module sets options inside `perSystem`, for example `packages.slides` or | `nix build .#slides` | the slide deck | | `nix run .#watch-documentation` | live docs preview | | `nix run .#serve-slides` | live slides preview | -| `nix fmt .` | format `.nix` files with alejandra | -| `nix flake check` | build both sites + lint the Nix code | -| `nix develop` | a shell with the linters (alejandra, statix, deadnix) | +| `nix fmt` | format and lint (treefmt: alejandra, deadnix, statix, nixf-diagnose, shellcheck, sizelint) | +| `nix flake check` | build both sites, lint, and check the three lock files agree | +| `devenv shell` | the dev shell: `fmt`, `check`, `docs`, `slides`, `docs-build` | | `nix flake show` | list all of the above | ## Exports @@ -99,6 +107,6 @@ input or copy the build. Consumer config is one line: ## Other systems -The flake builds for `x86_64-linux`. Add `"aarch64-linux"` or -`"aarch64-darwin"` to `systems` in `flake.nix` to build on ARM Linux or -Apple Silicon Macs. +The flake builds for `x86_64-linux` and `aarch64-linux`. Add +`"aarch64-darwin"` to `systems` in `flake.nix` to build on Apple Silicon +Macs. diff --git a/documentation/docs/presentation.md b/documentation/docs/presentation.md index a40a041..db5d731 100644 --- a/documentation/docs/presentation.md +++ b/documentation/docs/presentation.md @@ -1,14 +1,14 @@ # Presentation -The slide deck from `slides/`, embedded in this site. Click it and use the -arrow keys, or open it on its own. +The slide deck from `documentation/slides/`, embedded in this site. Click it and use the +arrow keys, or open it on its own. - diff --git a/documentation/docs/reveal-js.md b/documentation/docs/reveal-js.md index 3b6fc47..2aa40fc 100644 --- a/documentation/docs/reveal-js.md +++ b/documentation/docs/reveal-js.md @@ -7,12 +7,12 @@ repo you write the slides in Markdown and never touch JavaScript tooling. ## The files ```text -slides/ +documentation/slides/ ├── index.html # the page: loads reveal.js, picks a theme, points at slides.md └── slides.md # the slides themselves, in Markdown ``` -When you build, Nix copies `slides/`, folds `slides.md` into +When you build, Nix copies `documentation/slides/`, folds `slides.md` into `index.html`, and adds reveal.js under `reveal/`: ```text @@ -21,7 +21,7 @@ result/ └── reveal/ # reveal.js' prebuilt dist/: reveal.js, reveal.css, theme/, plugin/ ``` -You only edit `slides/`. To add images, put them in `slides/` (or a +You only edit `documentation/slides/`. To add images, put them in `documentation/slides/` (or a subfolder) and `git add` them. ## Writing slides in Markdown @@ -87,7 +87,7 @@ Chromium. ## Themes and settings -Change the theme in `slides/index.html`: +Change the theme in `documentation/slides/index.html`: ```html @@ -116,9 +116,9 @@ opens straight from disk and works on any host. `nix build .#documentation` also puts the built deck at `/slides/` of the website, and the [Presentation](presentation.md) page embeds it with an -`