nandi.uk
Nix packages for third-party projects that don't ship their own flakes
7.7 kB
239 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| `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` |
34
35## Usage
36
37```bash
38# build
39nix build .#vit
40nix build .#rook
41nix build .#spinel
42nix build .#boxd # x86_64-linux / aarch64-linux / aarch64-darwin
43nix build .#zed-preview # x86_64-linux only
44
45# run without installing
46nix run .#vit -- --help
47nix run .#rook -- --help
48nix run .#spinel -- --help
49nix run .#spin -- new myapp # spin project tool (from the spinel package)
50nix run .#boxd -- --help
51nix run .#zed-preview -- --version
52
53# install into your profile
54nix profile install .#vit
55nix profile install .#rook
56nix profile install .#spinel
57nix profile install .#boxd
58nix profile install .#zed-preview
59```
60
61## Updating packages
62
63### Automated (recommended)
64
65A GitHub Action runs **every Monday** (and on manual dispatch) to:
66
671. Read each `packages/*/upstream.json`
682. Compare the packaged version to the latest upstream tag
693. Refresh source hashes, regenerate lockfiles when needed, recompute `npmDepsHash`
704. Verify `nix build .#<pkg>`
715. Open a PR on branch `chore/update-packages` if anything changed
72
73```bash
74# local dry-run: exit 1 if any package is behind upstream
75./scripts/update-packages.sh --check
76
77# apply updates locally (requires nix, curl, npm)
78./scripts/update-packages.sh # all packages
79./scripts/update-packages.sh vit # one package
80```
81
82### `upstream.json`
83
84Supported types:
85
86**npm-github** — tagged npm projects:
87
88```json
89{
90 "type": "npm-github",
91 "github": "owner/repo",
92 "tag_prefix": "v"
93}
94```
95
96`npm-github` packages are expected to use `buildNpmPackage` + `fetchFromGitHub`
97with a `version` field and optional vendored `package-lock.json`.
98
99**github-unstable** — projects without release tags (track branch tip):
100
101```json
102{
103 "type": "github-unstable",
104 "github": "owner/repo",
105 "branch": "master"
106}
107```
108
109Versions are `0-unstable-YYYY-MM-DD` with a pinned `rev` in `fetchFromGitHub`.
110For spinel, the updater also re-reads `PRISM_VERSION` / `RBS_VERSION` from the
111upstream Makefile and refreshes the vendored gem hashes when they change.
112
113**github-release-binary** — prebuilt release assets (no source build):
114
115```json
116{
117 "type": "github-release-binary",
118 "github": "owner/repo",
119 "tag_prefix": "v",
120 "tag_suffix": "-pre",
121 "asset": "zed-linux-x86_64.tar.gz"
122}
123```
124
125Tracks the newest non-draft GitHub release whose tag matches
126`{tag_prefix}{semver}{tag_suffix}` and refreshes the `fetchurl` hash for
127`asset`. Used by `zed-preview` (x86_64-linux only).
128
129**url-manifest-binary** — prebuilt multi-platform binaries via a version
130manifest URL (not GitHub releases):
131
132```json
133{
134 "type": "url-manifest-binary",
135 "manifest_url": "https://boxd.sh/downloads/cli/latest-{platform}.json",
136 "platforms": {
137 "x86_64-linux": "linux-amd64",
138 "aarch64-linux": "linux-arm64",
139 "aarch64-darwin": "darwin-arm64"
140 }
141}
142```
143
144`{platform}` is replaced per entry in `platforms`. Each manifest must expose
145`version` + `url`; the updater prefetches every platform hash and rewrites the
146`sources = { … }` block in `default.nix`. Used by `boxd`.
147
148### Manual steps (vit / rook)
149
150If you prefer to bump by hand (same flow for either npm-github package):
151
1521. Bump `version` in `packages/<name>/default.nix`.
1532. Prefetch the new source hash:
154 ```bash
155 nix-prefetch-url --unpack "https://github.com/solpbc/<name>/archive/refs/tags/vX.Y.Z.tar.gz"
156 nix hash convert --hash-algo sha256 --to sri <base32>
157 ```
1583. Regenerate a lockfile with resolved URLs when needed:
159 ```bash
160 tmp=$(mktemp -d) && cd "$tmp"
161 curl -sL "https://github.com/solpbc/<name>/archive/refs/tags/vX.Y.Z.tar.gz" | tar -xz
162 cd <name>-X.Y.Z
163 rm -f package-lock.json bun.lock
164 npm install --package-lock-only --ignore-scripts
165 cp package-lock.json /path/to/this/repo/packages/<name>/package-lock.json
166 ```
1674. Set `npmDepsHash` to the all-zero fake hash, run `nix build .#<name>`, paste
168 the hash nix prints as `got:`, rebuild.
169
170Or just run `./scripts/update-packages.sh vit` / `./scripts/update-packages.sh rook`.
171
172### Manual steps (spinel)
173
174Spinel has no release tags yet, so the package pins a git commit as
175`0-unstable-YYYY-MM-DD`. Prefer the updater:
176
177```bash
178./scripts/update-packages.sh spinel
179```
180
181By hand:
182
1831. Bump `version`, `rev`, and the `fetchFromGitHub` `hash` in
184 `packages/spinel/default.nix`.
1852. If upstream changed `PRISM_VERSION` / `RBS_VERSION` in its Makefile, update
186 `prismVersion` / `rbsVersion` and re-hash the gems:
187 ```bash
188 nix-prefetch-url "https://rubygems.org/gems/prism-X.Y.Z.gem"
189 nix-prefetch-url "https://rubygems.org/gems/rbs-X.Y.Z.gem"
190 nix hash convert --hash-algo sha256 --to sri <base32>
191 ```
1923. `nix build .#spinel` and smoke-test `./result/bin/spinel -e 'puts 1'`.
193
194### Manual steps (zed-preview)
195
196`zed-preview` ships official Linux x86_64 preview binaries (tags `vX.Y.Z-pre`).
197Prefer the updater:
198
199```bash
200./scripts/update-packages.sh zed-preview
201```
202
203By hand:
204
2051. Bump `version` in `packages/zed-preview/default.nix` (e.g. `1.12.0-pre`).
2062. Prefetch the tarball hash:
207 ```bash
208 nix-prefetch-url "https://github.com/zed-industries/zed/releases/download/vX.Y.Z-pre/zed-linux-x86_64.tar.gz"
209 nix hash convert --hash-algo sha256 --to sri <base32>
210 ```
2113. Paste the SRI hash into `fetchurl.hash`, then `nix build .#zed-preview` and
212 smoke-test `./result/bin/zed-preview --version`.
213
214### Manual steps (boxd)
215
216`boxd` ships official static CLI binaries from [boxd.sh](https://boxd.sh)
217(see [quickstart](https://docs.boxd.sh/quickstart)). Prefer the updater:
218
219```bash
220./scripts/update-packages.sh boxd
221```
222
223By hand:
224
2251. Read the manifests and note the shared version:
226 ```bash
227 curl -fsSL https://boxd.sh/downloads/cli/latest-linux-amd64.json
228 curl -fsSL https://boxd.sh/downloads/cli/latest-linux-arm64.json
229 curl -fsSL https://boxd.sh/downloads/cli/latest-darwin-arm64.json
230 ```
2312. Bump `version` in `packages/boxd/default.nix`.
2323. Prefetch each platform binary hash into the matching `sources.<system>.hash`:
233 ```bash
234 nix-prefetch-url "https://boxd.sh/downloads/cli/boxd-linux-amd64"
235 nix-prefetch-url "https://boxd.sh/downloads/cli/boxd-linux-arm64"
236 nix-prefetch-url "https://boxd.sh/downloads/cli/boxd-darwin-arm64"
237 nix hash convert --hash-algo sha256 --to sri <base32>
238 ```
2394. `nix build .#boxd` and smoke-test `./result/bin/boxd --version`.