nandi.uk
Nix packages for third-party projects that don't ship their own flakes
12 kB
341 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| `boxd` | [boxd.sh](https://boxd.sh) / [docs](https://docs.boxd.sh/quickstart) | `curl -fsSL https://boxd.sh/downloads/install.sh \| sh` |
33| `whetuu` | [yamafaktory/whetuu](https://github.com/yamafaktory/whetuu) | [install script](https://yamafaktory.github.io/whetuu/install.sh) / release tarballs |
34| `pullrun` | [pullrun/pullrun](https://github.com/pullrun/pullrun) | `curl -fsSL https://github.com/pullrun/pullrun/raw/main/install.sh \| bash` |
35| `gleam-preview` | [gleam-lang/gleam](https://github.com/gleam-lang/gleam) (prereleases) | [install docs](https://gleam.run/getting-started/installing/) / release tarballs |
36| `zed-preview` | [zed-industries/zed](https://github.com/zed-industries/zed) (preview channel) | [official Linux installer](https://zed.dev/docs/linux) / `zed-linux-x86_64.tar.gz` |
37
38## Usage
39
40```bash
41# build
42nix build .#vit
43nix build .#rook
44nix build .#spinel
45nix build .#boxd # x86_64-linux / aarch64-linux / aarch64-darwin
46nix build .#whetuu # linux + darwin (all four systems)
47nix build .#pullrun # linux + darwin (all four systems)
48nix build .#gleam-preview # linux + darwin (all four systems)
49nix build .#zed-preview # x86_64-linux only
50
51# run without installing
52nix run .#vit -- --help
53nix run .#rook -- --help
54nix run .#spinel -- --help
55nix run .#spin -- new myapp # spin project tool (from the spinel package)
56nix run .#boxd -- --help
57nix run .#whetuu -- --version
58nix run .#pullrun -- --version
59nix run .#gleam-preview -- --version
60nix run .#zed-preview -- --version
61
62# install into your profile
63nix profile install .#vit
64nix profile install .#rook
65nix profile install .#spinel
66nix profile install .#boxd
67nix profile install .#whetuu
68nix profile install .#pullrun
69nix profile install .#gleam-preview
70nix profile install .#zed-preview
71```
72
73## Updating packages
74
75### Automated (recommended)
76
77A GitHub Action runs **every Monday** (and on manual dispatch) to:
78
791. Read each `packages/*/upstream.json`
802. Compare the packaged version to the latest upstream tag
813. Refresh source hashes, regenerate lockfiles when needed, recompute `npmDepsHash`
824. Verify `nix build .#<pkg>`
835. Open a PR on branch `chore/update-packages` if anything changed
84
85```bash
86# local dry-run: exit 1 if any package is behind upstream
87./scripts/update-packages.sh --check
88
89# apply updates locally (requires nix, curl, npm)
90./scripts/update-packages.sh # all packages
91./scripts/update-packages.sh vit # one package
92```
93
94### `upstream.json`
95
96Supported types:
97
98**npm-github** — tagged npm projects:
99
100```json
101{
102 "type": "npm-github",
103 "github": "owner/repo",
104 "tag_prefix": "v"
105}
106```
107
108`npm-github` packages are expected to use `buildNpmPackage` + `fetchFromGitHub`
109with a `version` field and optional vendored `package-lock.json`.
110
111**github-unstable** — projects without release tags (track branch tip):
112
113```json
114{
115 "type": "github-unstable",
116 "github": "owner/repo",
117 "branch": "master"
118}
119```
120
121Versions are `0-unstable-YYYY-MM-DD` with a pinned `rev` in `fetchFromGitHub`.
122For spinel, the updater also re-reads `PRISM_VERSION` / `RBS_VERSION` from the
123upstream Makefile and refreshes the vendored gem hashes when they change.
124
125**github-release-binary** — prebuilt release assets (no source build):
126
127Single-asset:
128
129```json
130{
131 "type": "github-release-binary",
132 "github": "owner/repo",
133 "tag_prefix": "v",
134 "tag_suffix": "-pre",
135 "asset": "zed-linux-x86_64.tar.gz"
136}
137```
138
139Multi-platform (`sources = { … }` block, like `url-manifest-binary`):
140
141```json
142{
143 "type": "github-release-binary",
144 "github": "owner/repo",
145 "tag_prefix": "v",
146 "platforms": {
147 "x86_64-linux": "tool-v{version}-x86_64-linux-musl.tar.gz",
148 "aarch64-linux": "tool-v{version}-aarch64-linux-musl.tar.gz",
149 "x86_64-darwin": "tool-v{version}-x86_64-macos.tar.gz",
150 "aarch64-darwin": "tool-v{version}-aarch64-macos.tar.gz"
151 }
152}
153```
154
155Tracks the newest non-draft GitHub release whose tag matches
156`{tag_prefix}{semver}{tag_suffix}`. Set `"tag_prerelease": true` to match any
157prerelease tag (`vX.Y.Z-rc1`, `vX.Y.Z-beta`, …) instead of a fixed suffix.
158Single-asset mode refreshes one `fetchurl` hash; multi-platform mode rewrites
159every `sources.<system>.{url,hash}`. `{version}` in asset names is the bare
160version (no tag prefix). Used by `zed-preview` (single), `whetuu` /
161`gleam-preview` / `pullrun` (multi).
162
163**url-manifest-binary** — prebuilt multi-platform binaries via a version
164manifest URL (not GitHub releases):
165
166```json
167{
168 "type": "url-manifest-binary",
169 "manifest_url": "https://boxd.sh/downloads/cli/latest-{platform}.json",
170 "platforms": {
171 "x86_64-linux": "linux-amd64",
172 "aarch64-linux": "linux-arm64",
173 "aarch64-darwin": "darwin-arm64"
174 }
175}
176```
177
178`{platform}` is replaced per entry in `platforms`. Each manifest must expose
179`version` + `url`; the updater prefetches every platform hash and rewrites the
180`sources = { … }` block in `default.nix`. Used by `boxd`.
181
182### Manual steps (vit / rook)
183
184If you prefer to bump by hand (same flow for either npm-github package):
185
1861. Bump `version` in `packages/<name>/default.nix`.
1872. Prefetch the new source hash:
188 ```bash
189 nix-prefetch-url --unpack "https://github.com/solpbc/<name>/archive/refs/tags/vX.Y.Z.tar.gz"
190 nix hash convert --hash-algo sha256 --to sri <base32>
191 ```
1923. Regenerate a lockfile with resolved URLs when needed:
193 ```bash
194 tmp=$(mktemp -d) && cd "$tmp"
195 curl -sL "https://github.com/solpbc/<name>/archive/refs/tags/vX.Y.Z.tar.gz" | tar -xz
196 cd <name>-X.Y.Z
197 rm -f package-lock.json bun.lock
198 npm install --package-lock-only --ignore-scripts
199 cp package-lock.json /path/to/this/repo/packages/<name>/package-lock.json
200 ```
2014. Set `npmDepsHash` to the all-zero fake hash, run `nix build .#<name>`, paste
202 the hash nix prints as `got:`, rebuild.
203
204Or just run `./scripts/update-packages.sh vit` / `./scripts/update-packages.sh rook`.
205
206### Manual steps (spinel)
207
208Spinel has no release tags yet, so the package pins a git commit as
209`0-unstable-YYYY-MM-DD`. Prefer the updater:
210
211```bash
212./scripts/update-packages.sh spinel
213```
214
215By hand:
216
2171. Bump `version`, `rev`, and the `fetchFromGitHub` `hash` in
218 `packages/spinel/default.nix`.
2192. If upstream changed `PRISM_VERSION` / `RBS_VERSION` in its Makefile, update
220 `prismVersion` / `rbsVersion` and re-hash the gems:
221 ```bash
222 nix-prefetch-url "https://rubygems.org/gems/prism-X.Y.Z.gem"
223 nix-prefetch-url "https://rubygems.org/gems/rbs-X.Y.Z.gem"
224 nix hash convert --hash-algo sha256 --to sri <base32>
225 ```
2263. `nix build .#spinel` and smoke-test `./result/bin/spinel -e 'puts 1'`.
227
228### Manual steps (zed-preview)
229
230`zed-preview` ships official Linux x86_64 preview binaries (tags `vX.Y.Z-pre`).
231Prefer the updater:
232
233```bash
234./scripts/update-packages.sh zed-preview
235```
236
237By hand:
238
2391. Bump `version` in `packages/zed-preview/default.nix` (e.g. `1.12.0-pre`).
2402. Prefetch the tarball hash:
241 ```bash
242 nix-prefetch-url "https://github.com/zed-industries/zed/releases/download/vX.Y.Z-pre/zed-linux-x86_64.tar.gz"
243 nix hash convert --hash-algo sha256 --to sri <base32>
244 ```
2453. Paste the SRI hash into `fetchurl.hash`, then `nix build .#zed-preview` and
246 smoke-test `./result/bin/zed-preview --version`.
247
248### Manual steps (boxd)
249
250`boxd` ships official static CLI binaries from [boxd.sh](https://boxd.sh)
251(see [quickstart](https://docs.boxd.sh/quickstart)). Prefer the updater:
252
253```bash
254./scripts/update-packages.sh boxd
255```
256
257By hand:
258
2591. Read the manifests and note the shared version:
260 ```bash
261 curl -fsSL https://boxd.sh/downloads/cli/latest-linux-amd64.json
262 curl -fsSL https://boxd.sh/downloads/cli/latest-linux-arm64.json
263 curl -fsSL https://boxd.sh/downloads/cli/latest-darwin-arm64.json
264 ```
2652. Bump `version` in `packages/boxd/default.nix`.
2663. Prefetch each platform binary hash into the matching `sources.<system>.hash`:
267 ```bash
268 nix-prefetch-url "https://boxd.sh/downloads/cli/boxd-linux-amd64"
269 nix-prefetch-url "https://boxd.sh/downloads/cli/boxd-linux-arm64"
270 nix-prefetch-url "https://boxd.sh/downloads/cli/boxd-darwin-arm64"
271 nix hash convert --hash-algo sha256 --to sri <base32>
272 ```
2734. `nix build .#boxd` and smoke-test `./result/bin/boxd --version`.
274
275### Manual steps (whetuu)
276
277`whetuu` ships official multi-platform release tarballs (static musl on Linux).
278Prefer the updater:
279
280```bash
281./scripts/update-packages.sh whetuu
282```
283
284By hand:
285
2861. Bump `version` in `packages/whetuu/default.nix` (e.g. `0.1.5`).
2872. Update each `sources.<system>.url` to the matching release asset and prefetch:
288 ```bash
289 nix-prefetch-url "https://github.com/yamafaktory/whetuu/releases/download/vX.Y.Z/whetuu-vX.Y.Z-x86_64-linux-musl.tar.gz"
290 nix-prefetch-url "https://github.com/yamafaktory/whetuu/releases/download/vX.Y.Z/whetuu-vX.Y.Z-aarch64-linux-musl.tar.gz"
291 nix-prefetch-url "https://github.com/yamafaktory/whetuu/releases/download/vX.Y.Z/whetuu-vX.Y.Z-x86_64-macos.tar.gz"
292 nix-prefetch-url "https://github.com/yamafaktory/whetuu/releases/download/vX.Y.Z/whetuu-vX.Y.Z-aarch64-macos.tar.gz"
293 nix hash convert --hash-algo sha256 --to sri <base32>
294 ```
2953. `nix build .#whetuu` and smoke-test `./result/bin/whetuu --version`.
296
297### Manual steps (pullrun)
298
299`pullrun` ships official multi-platform release tarballs (CLI + runtime, static).
300Prefer the updater:
301
302```bash
303./scripts/update-packages.sh pullrun
304```
305
306By hand:
307
3081. Bump `version` in `packages/pullrun/default.nix` (e.g. `0.6.7`).
3092. Update each `sources.<system>.url` to the matching release asset and prefetch:
310 ```bash
311 nix-prefetch-url "https://github.com/pullrun/pullrun/releases/download/vX.Y.Z/pullrun-X.Y.Z-linux-amd64.tar.gz"
312 nix-prefetch-url "https://github.com/pullrun/pullrun/releases/download/vX.Y.Z/pullrun-X.Y.Z-linux-arm64.tar.gz"
313 nix-prefetch-url "https://github.com/pullrun/pullrun/releases/download/vX.Y.Z/pullrun-X.Y.Z-darwin-amd64.tar.gz"
314 nix-prefetch-url "https://github.com/pullrun/pullrun/releases/download/vX.Y.Z/pullrun-X.Y.Z-darwin-arm64.tar.gz"
315 nix hash convert --hash-algo sha256 --to sri <base32>
316 ```
3173. `nix build .#pullrun` and smoke-test `./result/bin/pullrun --version` and
318 `./result/bin/pullrun-runtime --version`.
319
320### Manual steps (gleam-preview)
321
322`gleam-preview` ships official multi-platform prerelease binaries (tags
323`vX.Y.Z-rcN`, etc.). The binary is installed as `gleam-preview` so it can
324coexist with nixpkgs `gleam`. Prefer the updater:
325
326```bash
327./scripts/update-packages.sh gleam-preview
328```
329
330By hand:
331
3321. Bump `version` in `packages/gleam-preview/default.nix` (e.g. `1.18.0-rc1`).
3332. Update each `sources.<system>.url` to the matching release asset and prefetch:
334 ```bash
335 nix-prefetch-url "https://github.com/gleam-lang/gleam/releases/download/vX.Y.Z-rcN/gleam-vX.Y.Z-rcN-x86_64-unknown-linux-musl.tar.gz"
336 nix-prefetch-url "https://github.com/gleam-lang/gleam/releases/download/vX.Y.Z-rcN/gleam-vX.Y.Z-rcN-aarch64-unknown-linux-musl.tar.gz"
337 nix-prefetch-url "https://github.com/gleam-lang/gleam/releases/download/vX.Y.Z-rcN/gleam-vX.Y.Z-rcN-x86_64-apple-darwin.tar.gz"
338 nix-prefetch-url "https://github.com/gleam-lang/gleam/releases/download/vX.Y.Z-rcN/gleam-vX.Y.Z-rcN-aarch64-apple-darwin.tar.gz"
339 nix hash convert --hash-algo sha256 --to sri <base32>
340 ```
3413. `nix build .#gleam-preview` and smoke-test `./result/bin/gleam-preview --version`.