nandi.uk
Nix packages for third-party projects that don't ship their own flakes
11 kB
312 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| `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` |
36
37## Usage
38
39```bash
40# build
41nix build .#vit
42nix build .#rook
43nix build .#spinel
44nix build .#boxd # x86_64-linux / aarch64-linux / aarch64-darwin
45nix build .#whetuu # linux + darwin (all four systems)
46nix build .#pullrun # linux + darwin (all four systems)
47nix build .#zed-preview # x86_64-linux only
48
49# run without installing
50nix run .#vit -- --help
51nix run .#rook -- --help
52nix run .#spinel -- --help
53nix run .#spin -- new myapp # spin project tool (from the spinel package)
54nix run .#boxd -- --help
55nix run .#whetuu -- --version
56nix run .#pullrun -- --version
57nix run .#zed-preview -- --version
58
59# install into your profile
60nix profile install .#vit
61nix profile install .#rook
62nix profile install .#spinel
63nix profile install .#boxd
64nix profile install .#whetuu
65nix profile install .#pullrun
66nix profile install .#zed-preview
67```
68
69## Updating packages
70
71### Automated (recommended)
72
73A GitHub Action runs **every Monday** (and on manual dispatch) to:
74
751. Read each `packages/*/upstream.json`
762. Compare the packaged version to the latest upstream tag
773. Refresh source hashes, regenerate lockfiles when needed, recompute `npmDepsHash`
784. Verify `nix build .#<pkg>`
795. Open a PR on branch `chore/update-packages` if anything changed
80
81```bash
82# local dry-run: exit 1 if any package is behind upstream
83./scripts/update-packages.sh --check
84
85# apply updates locally (requires nix, curl, npm)
86./scripts/update-packages.sh # all packages
87./scripts/update-packages.sh vit # one package
88```
89
90### `upstream.json`
91
92Supported types:
93
94**npm-github** — tagged npm projects:
95
96```json
97{
98 "type": "npm-github",
99 "github": "owner/repo",
100 "tag_prefix": "v"
101}
102```
103
104`npm-github` packages are expected to use `buildNpmPackage` + `fetchFromGitHub`
105with a `version` field and optional vendored `package-lock.json`.
106
107**github-unstable** — projects without release tags (track branch tip):
108
109```json
110{
111 "type": "github-unstable",
112 "github": "owner/repo",
113 "branch": "master"
114}
115```
116
117Versions are `0-unstable-YYYY-MM-DD` with a pinned `rev` in `fetchFromGitHub`.
118For spinel, the updater also re-reads `PRISM_VERSION` / `RBS_VERSION` from the
119upstream Makefile and refreshes the vendored gem hashes when they change.
120
121**github-release-binary** — prebuilt release assets (no source build):
122
123Single-asset:
124
125```json
126{
127 "type": "github-release-binary",
128 "github": "owner/repo",
129 "tag_prefix": "v",
130 "tag_suffix": "-pre",
131 "asset": "zed-linux-x86_64.tar.gz"
132}
133```
134
135Multi-platform (`sources = { … }` block, like `url-manifest-binary`):
136
137```json
138{
139 "type": "github-release-binary",
140 "github": "owner/repo",
141 "tag_prefix": "v",
142 "platforms": {
143 "x86_64-linux": "tool-v{version}-x86_64-linux-musl.tar.gz",
144 "aarch64-linux": "tool-v{version}-aarch64-linux-musl.tar.gz",
145 "x86_64-darwin": "tool-v{version}-x86_64-macos.tar.gz",
146 "aarch64-darwin": "tool-v{version}-aarch64-macos.tar.gz"
147 }
148}
149```
150
151Tracks the newest non-draft GitHub release whose tag matches
152`{tag_prefix}{semver}{tag_suffix}`. Single-asset mode refreshes one `fetchurl`
153hash; multi-platform mode rewrites every `sources.<system>.{url,hash}`.
154`{version}` in asset names is the bare version (no tag prefix). Used by
155`zed-preview` (single) and `whetuu` (multi).
156
157**url-manifest-binary** — prebuilt multi-platform binaries via a version
158manifest URL (not GitHub releases):
159
160```json
161{
162 "type": "url-manifest-binary",
163 "manifest_url": "https://boxd.sh/downloads/cli/latest-{platform}.json",
164 "platforms": {
165 "x86_64-linux": "linux-amd64",
166 "aarch64-linux": "linux-arm64",
167 "aarch64-darwin": "darwin-arm64"
168 }
169}
170```
171
172`{platform}` is replaced per entry in `platforms`. Each manifest must expose
173`version` + `url`; the updater prefetches every platform hash and rewrites the
174`sources = { … }` block in `default.nix`. Used by `boxd`.
175
176### Manual steps (vit / rook)
177
178If you prefer to bump by hand (same flow for either npm-github package):
179
1801. Bump `version` in `packages/<name>/default.nix`.
1812. Prefetch the new source hash:
182 ```bash
183 nix-prefetch-url --unpack "https://github.com/solpbc/<name>/archive/refs/tags/vX.Y.Z.tar.gz"
184 nix hash convert --hash-algo sha256 --to sri <base32>
185 ```
1863. Regenerate a lockfile with resolved URLs when needed:
187 ```bash
188 tmp=$(mktemp -d) && cd "$tmp"
189 curl -sL "https://github.com/solpbc/<name>/archive/refs/tags/vX.Y.Z.tar.gz" | tar -xz
190 cd <name>-X.Y.Z
191 rm -f package-lock.json bun.lock
192 npm install --package-lock-only --ignore-scripts
193 cp package-lock.json /path/to/this/repo/packages/<name>/package-lock.json
194 ```
1954. Set `npmDepsHash` to the all-zero fake hash, run `nix build .#<name>`, paste
196 the hash nix prints as `got:`, rebuild.
197
198Or just run `./scripts/update-packages.sh vit` / `./scripts/update-packages.sh rook`.
199
200### Manual steps (spinel)
201
202Spinel has no release tags yet, so the package pins a git commit as
203`0-unstable-YYYY-MM-DD`. Prefer the updater:
204
205```bash
206./scripts/update-packages.sh spinel
207```
208
209By hand:
210
2111. Bump `version`, `rev`, and the `fetchFromGitHub` `hash` in
212 `packages/spinel/default.nix`.
2132. If upstream changed `PRISM_VERSION` / `RBS_VERSION` in its Makefile, update
214 `prismVersion` / `rbsVersion` and re-hash the gems:
215 ```bash
216 nix-prefetch-url "https://rubygems.org/gems/prism-X.Y.Z.gem"
217 nix-prefetch-url "https://rubygems.org/gems/rbs-X.Y.Z.gem"
218 nix hash convert --hash-algo sha256 --to sri <base32>
219 ```
2203. `nix build .#spinel` and smoke-test `./result/bin/spinel -e 'puts 1'`.
221
222### Manual steps (zed-preview)
223
224`zed-preview` ships official Linux x86_64 preview binaries (tags `vX.Y.Z-pre`).
225Prefer the updater:
226
227```bash
228./scripts/update-packages.sh zed-preview
229```
230
231By hand:
232
2331. Bump `version` in `packages/zed-preview/default.nix` (e.g. `1.12.0-pre`).
2342. Prefetch the tarball hash:
235 ```bash
236 nix-prefetch-url "https://github.com/zed-industries/zed/releases/download/vX.Y.Z-pre/zed-linux-x86_64.tar.gz"
237 nix hash convert --hash-algo sha256 --to sri <base32>
238 ```
2393. Paste the SRI hash into `fetchurl.hash`, then `nix build .#zed-preview` and
240 smoke-test `./result/bin/zed-preview --version`.
241
242### Manual steps (boxd)
243
244`boxd` ships official static CLI binaries from [boxd.sh](https://boxd.sh)
245(see [quickstart](https://docs.boxd.sh/quickstart)). Prefer the updater:
246
247```bash
248./scripts/update-packages.sh boxd
249```
250
251By hand:
252
2531. Read the manifests and note the shared version:
254 ```bash
255 curl -fsSL https://boxd.sh/downloads/cli/latest-linux-amd64.json
256 curl -fsSL https://boxd.sh/downloads/cli/latest-linux-arm64.json
257 curl -fsSL https://boxd.sh/downloads/cli/latest-darwin-arm64.json
258 ```
2592. Bump `version` in `packages/boxd/default.nix`.
2603. Prefetch each platform binary hash into the matching `sources.<system>.hash`:
261 ```bash
262 nix-prefetch-url "https://boxd.sh/downloads/cli/boxd-linux-amd64"
263 nix-prefetch-url "https://boxd.sh/downloads/cli/boxd-linux-arm64"
264 nix-prefetch-url "https://boxd.sh/downloads/cli/boxd-darwin-arm64"
265 nix hash convert --hash-algo sha256 --to sri <base32>
266 ```
2674. `nix build .#boxd` and smoke-test `./result/bin/boxd --version`.
268
269### Manual steps (whetuu)
270
271`whetuu` ships official multi-platform release tarballs (static musl on Linux).
272Prefer the updater:
273
274```bash
275./scripts/update-packages.sh whetuu
276```
277
278By hand:
279
2801. Bump `version` in `packages/whetuu/default.nix` (e.g. `0.1.5`).
2812. Update each `sources.<system>.url` to the matching release asset and prefetch:
282 ```bash
283 nix-prefetch-url "https://github.com/yamafaktory/whetuu/releases/download/vX.Y.Z/whetuu-vX.Y.Z-x86_64-linux-musl.tar.gz"
284 nix-prefetch-url "https://github.com/yamafaktory/whetuu/releases/download/vX.Y.Z/whetuu-vX.Y.Z-aarch64-linux-musl.tar.gz"
285 nix-prefetch-url "https://github.com/yamafaktory/whetuu/releases/download/vX.Y.Z/whetuu-vX.Y.Z-x86_64-macos.tar.gz"
286 nix-prefetch-url "https://github.com/yamafaktory/whetuu/releases/download/vX.Y.Z/whetuu-vX.Y.Z-aarch64-macos.tar.gz"
287 nix hash convert --hash-algo sha256 --to sri <base32>
288 ```
2893. `nix build .#whetuu` and smoke-test `./result/bin/whetuu --version`.
290
291### Manual steps (pullrun)
292
293`pullrun` ships official multi-platform release tarballs (CLI + runtime, static).
294Prefer the updater:
295
296```bash
297./scripts/update-packages.sh pullrun
298```
299
300By hand:
301
3021. Bump `version` in `packages/pullrun/default.nix` (e.g. `0.6.7`).
3032. Update each `sources.<system>.url` to the matching release asset and prefetch:
304 ```bash
305 nix-prefetch-url "https://github.com/pullrun/pullrun/releases/download/vX.Y.Z/pullrun-X.Y.Z-linux-amd64.tar.gz"
306 nix-prefetch-url "https://github.com/pullrun/pullrun/releases/download/vX.Y.Z/pullrun-X.Y.Z-linux-arm64.tar.gz"
307 nix-prefetch-url "https://github.com/pullrun/pullrun/releases/download/vX.Y.Z/pullrun-X.Y.Z-darwin-amd64.tar.gz"
308 nix-prefetch-url "https://github.com/pullrun/pullrun/releases/download/vX.Y.Z/pullrun-X.Y.Z-darwin-arm64.tar.gz"
309 nix hash convert --hash-algo sha256 --to sri <base32>
310 ```
3113. `nix build .#pullrun` and smoke-test `./result/bin/pullrun --version` and
312 `./result/bin/pullrun-runtime --version`.