nandi.uk
Nix packages for third-party projects that don't ship their own flakes
4.6 kB
149 lines
1# agentic
2
3Nix packages for third-party tools that don't ship their own flakes.
4
5## Layout
6
7```
8flake.nix # flake entrypoint: exposes packages.* and apps.*
9flake.lock
10packages/
11 vit/ # one directory per package (callPackage style)
12 default.nix
13 package-lock.json # only when we need a fixed/regenerated lock
14 upstream.json # how CI discovers and bumps this package
15scripts/
16 update-packages.sh # version bump + hash/lock refresh
17.github/workflows/
18 update-packages.yml # weekly cron + manual dispatch
19```
20
21Add a new package by creating `packages/<name>/default.nix` and wiring it in
22`flake.nix` via `pkgs.callPackage ./packages/<name> { }`. For automated
23updates, also add `packages/<name>/upstream.json` (see below).
24
25## Packages
26
27| Attr | Upstream | Install (non-Nix) |
28|------|----------|-------------------|
29| `vit` | [solpbc/vit](https://github.com/solpbc/vit) | `npm install -g vit` |
30| `rook` | [solpbc/rook](https://github.com/solpbc/rook) | `npm install -g @solpbc/rook` |
31| `spinel` | [matz/spinel](https://github.com/matz/spinel) | build from source (`make deps && make && make install`) |
32
33## Usage
34
35```bash
36# build
37nix build .#vit
38nix build .#rook
39nix build .#spinel
40
41# run without installing
42nix run .#vit -- --help
43nix run .#rook -- --help
44nix run .#spinel -- --help
45nix run .#spin -- new myapp # spin project tool (from the spinel package)
46
47# install into your profile
48nix profile install .#vit
49nix profile install .#rook
50nix profile install .#spinel
51```
52
53## Updating packages
54
55### Automated (recommended)
56
57A GitHub Action runs **every Monday** (and on manual dispatch) to:
58
591. Read each `packages/*/upstream.json`
602. Compare the packaged version to the latest upstream tag
613. Refresh source hashes, regenerate lockfiles when needed, recompute `npmDepsHash`
624. Verify `nix build .#<pkg>`
635. Open a PR on branch `chore/update-packages` if anything changed
64
65```bash
66# local dry-run: exit 1 if any package is behind upstream
67./scripts/update-packages.sh --check
68
69# apply updates locally (requires nix, curl, npm)
70./scripts/update-packages.sh # all packages
71./scripts/update-packages.sh vit # one package
72```
73
74### `upstream.json`
75
76Supported types:
77
78**npm-github** — tagged npm projects:
79
80```json
81{
82 "type": "npm-github",
83 "github": "owner/repo",
84 "tag_prefix": "v"
85}
86```
87
88`npm-github` packages are expected to use `buildNpmPackage` + `fetchFromGitHub`
89with a `version` field and optional vendored `package-lock.json`.
90
91**github-unstable** — projects without release tags (track branch tip):
92
93```json
94{
95 "type": "github-unstable",
96 "github": "owner/repo",
97 "branch": "master"
98}
99```
100
101Versions are `0-unstable-YYYY-MM-DD` with a pinned `rev` in `fetchFromGitHub`.
102For spinel, the updater also re-reads `PRISM_VERSION` / `RBS_VERSION` from the
103upstream Makefile and refreshes the vendored gem hashes when they change.
104
105### Manual steps (vit / rook)
106
107If you prefer to bump by hand (same flow for either npm-github package):
108
1091. Bump `version` in `packages/<name>/default.nix`.
1102. Prefetch the new source hash:
111 ```bash
112 nix-prefetch-url --unpack "https://github.com/solpbc/<name>/archive/refs/tags/vX.Y.Z.tar.gz"
113 nix hash convert --hash-algo sha256 --to sri <base32>
114 ```
1153. Regenerate a lockfile with resolved URLs when needed:
116 ```bash
117 tmp=$(mktemp -d) && cd "$tmp"
118 curl -sL "https://github.com/solpbc/<name>/archive/refs/tags/vX.Y.Z.tar.gz" | tar -xz
119 cd <name>-X.Y.Z
120 rm -f package-lock.json bun.lock
121 npm install --package-lock-only --ignore-scripts
122 cp package-lock.json /path/to/this/repo/packages/<name>/package-lock.json
123 ```
1244. Set `npmDepsHash` to the all-zero fake hash, run `nix build .#<name>`, paste
125 the hash nix prints as `got:`, rebuild.
126
127Or just run `./scripts/update-packages.sh vit` / `./scripts/update-packages.sh rook`.
128
129### Manual steps (spinel)
130
131Spinel has no release tags yet, so the package pins a git commit as
132`0-unstable-YYYY-MM-DD`. Prefer the updater:
133
134```bash
135./scripts/update-packages.sh spinel
136```
137
138By hand:
139
1401. Bump `version`, `rev`, and the `fetchFromGitHub` `hash` in
141 `packages/spinel/default.nix`.
1422. If upstream changed `PRISM_VERSION` / `RBS_VERSION` in its Makefile, update
143 `prismVersion` / `rbsVersion` and re-hash the gems:
144 ```bash
145 nix-prefetch-url "https://rubygems.org/gems/prism-X.Y.Z.gem"
146 nix-prefetch-url "https://rubygems.org/gems/rbs-X.Y.Z.gem"
147 nix hash convert --hash-algo sha256 --to sri <base32>
148 ```
1493. `nix build .#spinel` and smoke-test `./result/bin/spinel -e 'puts 1'`.