Files
millerson-overlay.nix/docs/research_marmel_update_tooling.md
T
alex e569243ae4
CI / check (push) Has been cancelled
chore(marmel): bump to afcc1dc (main), give checks a usable TMPDIR
Track upstream main at afcc1dc971ae4acd59b157f031d4bdbc9d52a7d0
(2026-11-07), 22 commits past the de3e99c8 pin. Upstream still ships no
tags or releases and Cargo.toml still reads version 1.0.0, so the dated
0-unstable-* string stays. cargoHash moves on its own: the new
crates/zim-search workspace member grew Cargo.lock from 399 to 621
entries, and cargo vendor hashes the whole workspace.

The real packaging work is the TMPDIR override appended to preCheck.
Upstream's new harness::fs::path_tests scratch-root helper puts its
scratch dirs under <cwd>/target/ and first asserts that root lies
outside std::env::temp_dir(). The build sandbox exports TMPDIR=/build,
which is an ancestor of the unpacked source at /build/source, so that
premise check tripped and all 8 path-security tests failed with
"scoped root /build/source/target/marmel-path-tests-N sits inside the
temp allow-list entry /build". Pointing TMPDIR at
/tmp/marmel-check-tmp, outside $NIX_BUILD_TOP, restores upstream's
premise, so all 8 tests keep running for real instead of being filtered
out of cargoTestFlags. Build-time only; the installed binary is
untouched.

Two derivation comments carried stale facts and are corrected:

- meta.license claimed the repository shipped no LICENSE file and that
  Cargo.toml had no license field. Upstream c98179d023 (Na1w/marmel#40)
  added a root LICENSE file and declared license = "MIT" in Cargo.toml,
  so the comment now records that MIT is asserted in the README,
  Cargo.toml and LICENSE alike; lib.licenses.mit was already the right
  value.
- the cargoTestFlags comment quoted "the lib suite passes at 1055
  tests". Roughly 500 test fns landed since (TUI, fs-path, PTY and
  dispatch-integrity suites), so the figure is dropped rather than
  refreshed: nothing checks it and it rots on every bump.

Also adds the two research notes behind the bump under docs/: the
de3e99c8..afcc1dc9 upstream delta audit and the update-tooling findings.

Verified: clean nix build .#marmel including the serialised test suite
(--test-threads=1) — 2146 passed, 0 failed.
2026-11-07 16:54:02 +03:00

484 lines
25 KiB
Markdown

# marmel bump — tooling / feasibility inventory
**Repo:** `/home/minder/GIT/millerson.name/nix-overlay` (nix flake, `numtide/blueprint` + `flake-parts`)
**Target file:** `packages/marmel/package.nix` (`passthru.updateScript = [ "nix-update" "--flake" "marmel" "--version=branch=main" ]`)
**Probed:** 2026-11-07 ~11:00 UTC. Nothing in the repo was modified by this research
(`git diff --quiet -- packages/marmel/package.nix` → clean).
---
## 0. TL;DR — recommended command sequence
Run **from the repo root** (nix-update requires a git working tree, see §5.4):
```bash
cd /home/minder/GIT/millerson.name/nix-overlay
# nix-update is NOT on PATH but is one command away (substituted from cache in ~5 s)
nix shell nixpkgs#nix-update --command \
nix-update --flake --version=branch=main marmel
```
That command was **executed end-to-end in a throwaway copy of this repo and succeeded**
— it rewrote `version`, `rev`, `src.hash` and `cargoHash` in
`packages/marmel/package.nix` (exact diff in §4.4).
Then verify + format:
```bash
nix build .#marmel # long: ~621 crates compiled from the vendor tree
nix fmt packages/marmel/package.nix # already clean after nix-update (verified "0 changed")
```
### Verified result values (as of 2026-11-07)
| field | old | new |
|---|---|---|
| `version` | `0-unstable-2026-10-23` | `0-unstable-2026-11-07` |
| `src.rev` | `de3e99c89b18bf43fbb471930bd9f7a40e1ca1b2` | `afcc1dc971ae4acd59b157f031d4bdbc9d52a7d0` |
| `src.hash` | `sha256-Z8qvzwSTpri9M05xZ07PJi9xSYIgBOos9bDh0NijSZg=` | `sha256-OiF2Lc4s01MuXX2HfWMePBJ9M/uuhI69gInqqDPhbgQ=` |
| `cargoHash` | `sha256-FbtY6K+0tG7JymhG/PnK+SU7SW/IFjG8Wswt+EnWPhg=` | `sha256-Xw9OT8HXVlnZ0XqIMnnFwQ/y9xKxOtmcwomJsRxUx5E=` |
`afcc1dc971ae4acd59b157f031d4bdbc9d52a7d0` = `main` HEAD at probe time ("feat: isolate git
worktrees per task, plan merge steps, and commit as Marmel Coder (#46)", committer date
`2026-11-07T05:55:53Z`). **Re-check before bumping — upstream advances daily.**
`src.hash` was derived three independent ways, all agreeing (§4.2); `cargoHash` came from a
real `nix-build` hash-mismatch of the exact derivation nixpkgs uses for `cargoHash` (§4.3).
### Fallback one-liner (no nix-update)
```bash
SHA=$(curl -s https://api.github.com/repos/Na1w/marmel/commits/main \
| sed -n 's/.*"sha": "\([0-9a-f]\{40\}\)".*/\1/p' | head -1)
nix-prefetch-url --unpack "https://github.com/Na1w/marmel/archive/$SHA.tar.gz" \
| tail -1 | xargs -I{} nix hash convert --hash-algo sha256 --to sri {}
# then edit version/rev/src.hash by hand and let the build report cargoHash (§6.2)
```
Full fallback detail in §6.
---
## 1. `nix` — installed, flakes + nix-command enabled
| item | value |
|---|---|
| binary | `/run/current-system/sw/bin/nix` |
| version | **`nix (Nix) 2.34.9`** |
| `nix show-config` → `experimental-features` | **`fetch-tree flakes nix-command`** |
| `/etc/nix/nix.conf` → `experimental-features` | `nix-command flakes` |
| user `nix.conf` | none (`~/.config/nix/nix.conf` does not exist); no `nix.conf.d` |
| env vars | no `NIX_CONFIG`, no `NIX_FEATURES`. `NIX_PATH=nixpkgs=flake:nixpkgs:...` **is** set, so `with import <nixpkgs> {};` works (nix-update relies on this) |
| store / remote | `nix store ping` → `Store URL: daemon`, `Version: 2.34.9`, **`Trusted: 0`** |
| daemon | `nix-daemon --daemon` running; builds run as `nixbld1` |
| substituters | `https://mirror.yandex.ru/nixos`, `https://cache.numtide.com`, `https://cache.nixos.org/` (all reachable) |
**No `--extra-experimental-features` flag is needed** — `nix-command` + `flakes` are already
enabled system-wide.
Cosmetic noise: `nix.conf` carries a bogus
`sandbox_extra_readonly_paths = /home/minde/.beads` (typo'd home dir), so **every** nix
invocation prints `warning: ignoring sandbox_extra_readonly_paths entry "/home/minde/.beads": does not exist`.
## 2. Tool availability
| tool | on `PATH`? | notes |
|---|---|---|
| `nix` | yes | 2.34.9 |
| **`nix-update`** | **NO** | Not installed. Installable from cache: `nix shell nixpkgs#nix-update` → **1.15.1** (verified → `/nix/store/sxspafgpl5d4h4ipd945a6q4l7gsjvyw-nix-update-1.15.1`). Also already in store at `/nix/store/v5rgl0pm2qd5mwra66gfri6j1cc6v5fm-nix-update-1.15.1/bin/nix-update`. |
| `nix-prefetch-git` | **NO** | `nix shell nixpkgs#nix-prefetch-git` → 26.05 (verified working). **Not needed for this package** (§2.1). |
| `nix-prefetch-github` | **NO** | `nix shell nixpkgs#nix-prefetch-github` → 7.1.0 (verified working). |
| `prefetch-git` | no | not an attribute in current nixpkgs. |
| `nix-prefetch` | no | not a real command. |
| `nix-prefetch-url` | **yes** | `/run/current-system/sw/bin/nix-prefetch-url` (ships with nix) — use it for the src hash (§4.2). |
| `nix-build`, `nix-shell`, `nix-instantiate`, `nix-env` | yes | `/run/current-system/sw/bin` (nix-update needs the first three). |
| `git` | yes | `/etc/profiles/per-user/minder/bin/git` (nix-update needs it). |
| `treefmt` / `nixfmt` | no | not on PATH; use `nix fmt` (§7). |
| `nom` | no | nix-update falls back to plain `nix`. |
`nix-update --version` is **not** a usable flag in 1.15.1 (`--version` is the "version to
update to" option; bare `--version` prints usage). Get the version from
`nix eval nixpkgs#nix-update.version` or the store path name.
### 2.1 nix-update's real external requirements
Grepped from
`/nix/store/v5rgl0pm2qd5mwra66gfri6j1cc6v5fm-nix-update-1.15.1/lib/python3.13/site-packages/nix_update/`:
`git`, `nix-build`, `nix-instantiate`, `nix-shell`, `nix` (`nix-command flakes`), and
`nix-prefetch-git` **only** in `git.py::git_prefetch`, used for `git+` entries in a Cargo.lock
that the package declares via `cargoLock.lockFile`.
For `marmel`: `Cargo.lock` at the new rev has **621 packages and 0 `git+` sources**, and
`package.nix` declares no `cargoLock`, so **`nix-prefetch-git` is never invoked**. nix-update
has zero references to `nix-prefetch-github` — it computes hashes itself (§5.3).
## 3. Network access — yes, including from inside the build sandbox
```
curl -I https://api.github.com -> HTTP 200 (0.53 s)
curl https://api.github.com/rate_limit -> core limit 60/h, 59 remaining (unauthenticated)
curl -I https://codeload.github.com/Na1w/marmel/tar.gz/refs/heads/main -> HTTP 200
curl -I https://cache.nixos.org/nix-cache-info -> HTTP 200
curl -I https://static.crates.io/ -> HTTP 403 (bare bucket root; crate fetches work)
curl https://github.com/Na1w/marmel/commits/main.atom -> Atom feed OK (nix-update's branch source)
```
GitHub unauthenticated API limit is **60 req/h**. `nix-prefetch-github` and nix-update's
release lookups consume it; the `commits/main.atom` feed used by `--version=branch=main`
is **not** API-rate-limited.
**Fixed-output derivations get network inside the sandbox — confirmed empirically:**
```
$ nix build --impure --expr 'let p = import <nixpkgs> {}; in p.fetchurl { url = "https://api.github.com/zen"; hash = ""; }'
error: hash mismatch in fixed-output derivation '/nix/store/9njz7kig2zzgv4h98381l3fv33nsv3db-zen.drv':
specified: sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=
got: sha256-pMlQmrUEDYRs2ap8pjC+ug40eC3aL1feTGB4DJBIFCU=
```
That `got: <hash>` line is exactly what nix-update parses, so hash computation works here.
## 4. Attribute exposure, and how to obtain the hashes
### 4.1 The exact attribute name
```bash
nix eval --impure --expr 'builtins.attrNames (builtins.getFlake "git+file:.").packages'
# -> [ "aarch64-darwin" "aarch64-linux" "x86_64-darwin" "x86_64-linux" ]
nix eval --impure --raw --expr 'builtins.concatStringsSep "\n" (builtins.attrNames (builtins.getFlake "git+file:.").packages.x86_64-linux)'
# -> agnix aionui awg-tool awgen codeaf container-use default desloppify ds4 flake-inputs
# freebuff freetoken g3 graphify haivemind hipengine kubernetes-mcp-server kyojin loop
# **marmel** mcp-gateway memdoor nftables-analyzer nftablesbuilder omniroute
# open-code-review pdfcraft pilotdeck radar relay-free-llm shardr skillsmcp stakpak traycer
```
`builtins.elem "marmel" (builtins.attrNames packages.<sys>)`:
| system | `packages.<sys>.marmel` |
|---|---|
| `x86_64-linux` | ✅ `true` (this machine's `builtins.currentSystem` — use it) |
| `aarch64-linux` | ✅ `true` |
| `aarch64-darwin` | ✅ `true` |
| `x86_64-darwin` | ❌ **eval errors** — pre-existing, unrelated: `error: Nixpkgs 26.11 has dropped support for x86_64-darwin.` (locked nixpkgs rev `eaad089433ca`, `lib.version = 26.11pre-git`). Never pass `--system x86_64-darwin`. |
**The attribute name to give `nix-update --flake` is the bare `marmel`** — the comment in
`package.nix` is correct. Mechanism: `Options.get_package()` (`nix_update/options.py`) builds
```nix
(let flake = builtins.getFlake <path>; in flake.packages.${builtins.currentSystem}.marmel or flake.marmel)
```
and `parse_attribute_path` raises `AttributePathError` on a leading dot, so `.#marmel` fails.
`nix flake show` renders it as `checks.<sys>.pkgs-marmel: derivation 'marmel-0-unstable-2026-10-23'`;
blueprint also emits `packages.<sys>.marmel` and a `packages.<sys>.default` launcher.
### 4.2 `src.hash` — three agreeing methods (all executed)
For rev `afcc1dc971ae4acd59b157f031d4bdbc9d52a7d0` →
**`sha256-OiF2Lc4s01MuXX2HfWMePBJ9M/uuhI69gInqqDPhbgQ=`**
1. **Empty-hash fixed-output build** (no installs needed):
```bash
nix build --impure --no-write-lock-file --no-link --expr '
let pkgs = import <nixpkgs> {}; in pkgs.fetchFromGitHub {
owner = "Na1w"; repo = "marmel";
rev = "afcc1dc971ae4acd59b157f031d4bdbc9d52a7d0";
hash = "";
}'
# error: hash mismatch ... got: sha256-OiF2Lc4s01MuXX2HfWMePBJ9M/uuhI69gInqqDPhbgQ=
```
2. `nix-prefetch-url --unpack https://github.com/Na1w/marmel/archive/<sha>.tar.gz`
→ `013fw4rsisl9h2yqx15fzcrps4iw3ripv1vxblp57lrcrqnpc89s`, then
`nix hash convert --hash-algo sha256 --to sri <hex>` → same SRI.
3. `nix-prefetch-github Na1w marmel --rev <sha>` (after `nix shell nixpkgs#nix-prefetch-github`)
→ `{"owner":"Na1w","repo":"marmel","rev":"afcc1dc…","hash":"sha256-OiF2Lc4s01MuXX2HfWMePBJ9M/uuhI69gInqqDPhbgQ="}`
(7.1.0 already emits SRI — no `nix hash convert` needed).
`nix-prefetch-git https://github.com/Na1w/marmel <sha>` also agrees
(`"sha256": "013fw4rsisl9…"`, `"hash": "sha256-OiF2…"`).
### 4.3 `cargoHash` — it is `cargoDeps.vendorStaging`, not `cargoDeps`
The locked nixpkgs (26.11pre-git) no longer uses `fetchCargoTarball`:
* `pkgs/build-support/rust/build-rust-package/default.nix:114-132` maps `cargoHash` →
`fetchCargoVendor (… { hash = args.cargoHash; })`.
* `pkgs/build-support/rust/fetch-cargo-vendor.nix:74-107` puts `outputHash = hash` on an
inner `vendorStaging` derivation (`outputHashMode = "recursive"`, `outputHashAlgo = "sha256"`
when `hash == ""`).
So **`cargoHash == cargoDeps.vendorStaging.outputHash`** — exactly what nix-update 1.15.1
targets (`eval.nix`: `cargo_vendor_deps = pkg.cargoDeps.vendorStaging.outputHash or null;`,
`dependency_hashes.py`: `"cargo_vendor_deps" → update_hash_with_prefetch("cargoDeps.vendorStaging")`).
Verified recipe (~12 min for 621 crates; **read-only**, does not touch the repo):
```bash
cat > /tmp/cargohash.nix <<'EOF'
let
flake = builtins.getFlake "/home/minder/GIT/millerson.name/nix-overlay";
pkgs = import flake.inputs.nixpkgs { };
pkg = flake.packages.x86_64-linux.marmel.overrideAttrs (final: prev: {
src = pkgs.fetchFromGitHub {
owner = "Na1w"; repo = "marmel";
rev = "afcc1dc971ae4acd59b157f031d4bdbc9d52a7d0";
hash = "sha256-OiF2Lc4s01MuXX2HfWMePBJ9M/uuhI69gInqqDPhbgQ=";
};
});
vs = pkg.cargoDeps.vendorStaging or pkg.cargoDeps;
in vs.overrideAttrs (_: { outputHash = ""; outputHashAlgo = "sha256"; })
EOF
nix build --impure --no-write-lock-file --no-link --file /tmp/cargohash.nix
# error: hash mismatch in fixed-output derivation '…-marmel-0-unstable-…-vendor-staging.drv':
# got: sha256-Xw9OT8HXVlnZ0XqIMnnFwQ/y9xKxOtmcwomJsRxUx5E=
```
Two traps: `overrideSrc` **does not exist** in this nixpkgs (removed — `error: attribute
'overrideSrc' missing`), so use `overrideAttrs`; and `cargoDeps` is derived from
`finalAttrs.src`, so overriding `src` correctly recomputes the vendor derivation.
### 4.4 End-to-end nix-update verification (performed)
Run in a **copy** of the repo (`git archive HEAD` → `/tmp/marmel-bump-test`), leaving the real
repo untouched:
```bash
PATH=/nix/store/v5rgl0pm2qd5mwra66gfri6j1cc6v5fm-nix-update-1.15.1/bin:$PATH \
nix-update --flake --version=branch=main marmel
```
Produced diff (only these 4 lines changed):
```diff
- version = "0-unstable-2026-10-23";
+ version = "0-unstable-2026-11-07";
src = fetchFromGitHub {
owner = "Na1w";
repo = "marmel";
- rev = "de3e99c89b18bf43fbb471930bd9f7a40e1ca1b2";
- hash = "sha256-Z8qvzwSTpri9M05xZ07PJi9xSYIgBOos9bDh0NijSZg=";
+ rev = "afcc1dc971ae4acd59b157f031d4bdbc9d52a7d0";
+ hash = "sha256-OiF2Lc4s01MuXX2HfWMePBJ9M/uuhI69gInqqDPhbgQ=";
};
- cargoHash = "sha256-FbtY6K+0tG7JymhG/PnK+SU7SW/IFjG8Wswt+EnWPhg=";
+ cargoHash = "sha256-Xw9OT8HXVlnZ0XqIMnnFwQ/y9xKxOtmcwomJsRxUx5E=";
```
Comments, `nativeCheckInputs`, `preCheck`, `cargoTestFlags`, `postInstall`, `passthru` and
`meta` were left untouched. Reference copy kept at `/tmp/marmel-bump-test`.
**The only error in that run was an artifact of the copy not being a git repo**
(`git -C /tmp/marmel-bump-test/.. diff` → exit 129 in `git_has_diff`), raised *after* the file
was written. In the real repo it does not happen — but it means **nix-update must be run
inside the git working tree** (`validate_git_dir`).
## 5. nix-update deep-dive (1.15.1)
### 5.1 Version scheme
`--version=branch=main` → `VersionPreference.BRANCH` with branch `main`
(`version/version.py::from_str` accepts `branch` and `branch=<name>`). The fetcher is
`fetch_github_snapshots` (`version/github.py:144-199`), which reads
`https://github.com/Na1w/marmel/commits/main.atom`, takes the newest entry and emits
`Version(f"{version}-unstable-{date}", rev=commit)` where
`version_numbers = <release tag numbers> + ["0"]`. marmel publishes **no tags and no
releases** (`GET /repos/Na1w/marmel/tags` → `[]`), so the result is always
`0-unstable-YYYY-MM-DD` — exactly the existing convention. `date` is the Atom `<updated>`
of the head commit (`2026-11-07T05:55:53Z` → `2026-11-07`).
### 5.2 Which file it edits
`eval.nix` uses `builtins.unsafeGetAttrPos "src" pkg` and maps the store path back onto the
working tree (`sanitizePosition`, `flakeImportPath` from `nix flake metadata --json`). Verified:
it edited `packages/marmel/package.nix`, **not** the thin `packages/marmel/default.nix`
(`pkgs.callPackage ./package.nix { }`). No `--override-filename` needed.
### 5.3 How it computes hashes (no prefetch tools required)
`dependency_hashes.py::nix_prefetch` runs
```bash
nix-build --expr 'let src = <pkg>.src; in (src.overrideAttrs or (f: src // f src)) (_: { outputHash = ""; outputHashAlgo = "sha256"; })'
```
and regex-extracts `got: <hash>` from stderr (`extract_hash_from_nix_error`), then
`nix hash to-sri`. The identical trick is used for `cargoDeps.vendorStaging`. Hence no
`nix-prefetch-*` is required — but **fixed-output builds with network must work**, which §3 confirms.
### 5.4 Gotchas
* **Must run inside a git working tree** (post-update `git diff` in `git_has_diff`).
* The working tree is dirty (`.serena/project.yml` modified; `.marmel/` untracked). nix-update
copies the flake via `nix flake metadata --json`, so dirty tracked content is used and nix
prints `warning: Git tree … is dirty`. Harmless.
* **`--use-update-script` will fail as written.** `run_update_script` (`update.py:136-191`)
executes `passthru.updateScript` inside
`nix develop --impure --expr 'with import <nixpkgs> {}; pkgs.mkShell { inputsFrom = [ <pkg> ]; }'`.
`inputsFrom` supplies the *package's* build inputs (rustPlatform, cargo, cacert) — **not**
`nix-update` — and `nix-update` is not on the host PATH, so
`nix-update --flake marmel --use-update-script` (the command suggested by the comment in
`package.nix`) dies with `nix-update: command not found`. If you insist on the update-script
path, prefix it:
`nix shell nixpkgs#nix-update --command nix-update --flake marmel --use-update-script`.
Prefer the direct form in §0 (one less `nix develop` layer, and it avoids building
`inputsFrom`).
* `--format` shells out to a bare `nixfmt` (not on PATH) — use `nix fmt` afterwards instead.
* `--build` / `--test` / `--review` pull in extra tooling and a full compile; omit them.
* `--commit` would auto-commit; the repo's AGENTS.md wants conventional commits, so either use
it deliberately or commit manually (§8).
---
## 6. Fallback procedure (nix-update unavailable, or branch scheme unresolved)
### 6.1 Manual bump — three edits in `packages/marmel/package.nix`
1. `version = "0-unstable-YYYY-MM-DD";` — date = committer date of `main` HEAD:
```bash
curl -s https://api.github.com/repos/Na1w/marmel/commits/main \
| python3 -c 'import json,sys;d=json.load(sys.stdin);print(d["sha"]);print(d["commit"]["committer"]["date"])'
```
2. `rev` = full 40-char SHA; `hash` = §4.2 method 1, 2 or 3.
3. `cargoHash` = §6.2.
### 6.2 Getting `cargoHash` without nix-update
Both routes work on this box:
* **Let the build report it** (the flow AGENTS.md documents): write the new `rev`/`src.hash`,
then `nix build .#marmel`. The `…-marmel-…-vendor-staging` fixed-output derivation fails
*before* any rustc work with `got: sha256-…`; paste that into `cargoHash` and rebuild.
* **Read-only probe** (no file edit): the `/tmp/cargohash.nix` recipe in §4.3.
`prefetchCargoHash` / `prefetch-cargo-hash` are **not** commands on this system (nor in
nixpkgs) — don't look for them. Note that in this nixpkgs the mismatching derivation is
`<pname>-<version>-vendor-staging`, not `cargo-deps`; grepping build output for
`vendor-staging` locates it fast.
### 6.3 Sandbox / daemon constraints
* `sandbox = true`, `sandbox-fallback = false`, and this user is **not trusted**
(`nix store ping` → `Trusted: 0`; `trusted-users = root`).
* `__noChroot` derivations are therefore rejected — verified:
`error: derivation '…' has '__noChroot' set, but that's not allowed when 'sandbox' is 'true'`.
Good news: neither `fetchFromGitHub` nor `fetchCargoVendor`/`vendorStaging` sets
`__noChroot` (grepped in the locked nixpkgs), so **no sandbox bypass is needed** for this bump.
* `--option sandbox false` is silently ignored:
`warning: ignoring the client-specified setting 'sandbox', because it is a restricted setting and you are not a trusted user`.
Do **not** plan around `nix build --option sandbox false`; it does nothing here.
* Plain sandboxed builds work (`nix build nixpkgs#hello` substituted from `cache.numtide.com`;
a hand-made sandboxed derivation built successfully).
---
## 7. Repo conventions that matter for the edit
* **Formatter: `nix fmt <paths>` is the right command.**
`flake.formatter.x86_64-linux` = `/nix/store/b6mf3mzvln2igb244baas9vi6pywa05x-nixfmt-tree-2.6.0`
— a treefmt wrapper whose *generated* config is
`[formatter.nixfmt] command = "nixfmt"`, `includes = ["*.nix"]`, wrapping nixfmt **1.5.0**.
Verified: `nix fmt packages/marmel/package.nix` → `traversed 1 files / emitted 1 files /
formatted 1 files (0 changed)`, and nix-update's output is already format-clean.
Current `packages/marmel/package.nix` is also `nixfmt --check`-clean as-is.
* **The repo's `treefmt.toml` is effectively dead config.** `nix fmt` is handed the generated
config (`--config-file /nix/store/…-treefmt.toml`, formatter id `nixfmt`), so the repo's
`[formatter.nix]` section is never consulted. There is **no** `.pre-commit-config.yaml` and
no `treefmt.nix`; `treefmt-nix` is only an input feeding blueprint's formatter. README already
labels treefmt "(optional)".
* **`nix flake check` does NOT check formatting.** `checks.x86_64-linux` contains only
`pkgs-agnix … pkgs-marmel … pkgs-traycer` (one derivation per package → it *builds*
everything). Blueprint's `format-check` derivation is not wired into `checks`.
* **`devShells` is empty** → `nix develop` (suggested in AGENTS.md) does not work in this repo.
* **CI** (`.github/workflows/ci.yml`): `nix flake check`, then `nix build .#packages || true`.
* **Formatting scope**: run `nix fmt packages/marmel/package.nix`, not bare `nix fmt`
(bare invocation formats the whole `git ls-files` tree).
* **README** row for `marmel` (`README.md:29`) carries description + category only — no
version string, so a version bump needs no README edit.
* `overlays/` and `modules/` contain no `marmel` literal (blueprint auto-generates the overlay),
so `packages/marmel/package.nix` is the only file to touch.
* AGENTS.md §"Updating a Package Version" (~lines 209-215) and §"Updating Packages"
(~lines 284-307) already document this flow, including
`nix-update <package-name> --version=branch=main`.
---
## 8. Copy-paste runbook
```bash
cd /home/minder/GIT/millerson.name/nix-overlay
# 0. sanity: current state + who is upstream now
git status --short
curl -s https://api.github.com/repos/Na1w/marmel/commits/main \
| python3 -c 'import json,sys;d=json.load(sys.stdin);print(d["sha"], d["commit"]["committer"]["date"])'
# 1. bump (nix-update is not installed; pull it from the binary cache)
nix shell nixpkgs#nix-update --command nix-update --flake --version=branch=main marmel
# 2. inspect — expect exactly 4 changed lines (version, rev, src hash, cargoHash)
git diff -- packages/marmel/package.nix
# 3. format (expect "0 changed")
nix fmt packages/marmel/package.nix
# 4. build + run the package's own checks (long: full rust build)
nix build .#marmel
nix build .#checks.x86_64-linux.pkgs-marmel # same derivation via blueprint's check
# 5. commit (conventional commits, per AGENTS.md)
git add packages/marmel/package.nix
git commit -m "chore(marmel): bump 0-unstable-2026-10-23 -> 0-unstable-2026-11-07"
```
If step 1 is impossible, use §6.1 + §6.2 verbatim.
### Things to re-check after the bump
* `nativeCheckInputs = [ cacert ]`, the `preCheck` `SSL_CERT_FILE` export and
`cargoTestFlags` (`--test-threads=1`, skip
`harness::sandbox::tests::test_internal_sandbox_exec_dev_null_and_dns`) exist for reasons
documented in `package.nix` comments. Re-read those comments against the new rev: they claim
the lib suite passes **1055 tests** with that single skip at the old rev; a new upstream rev
can change the test count, rename the skipped test, or re-introduce flakiness. If a skip
filter stops matching, cargo prints `0 filtered out` and the suite silently under-tests.
* `meta.license = lib.licenses.mit` was asserted from the README because no LICENSE file
shipped; `Cargo.toml` at `afcc1dc` now has `license = "MIT"`, so the claim is better supported.
* `Cargo.toml` still says `version = "1.0.0"` (so the `0-unstable-*` scheme stays mandatory) and
`rust-version = "1.98"`. Confirm the locked nixpkgs toolchain still satisfies it; if upstream
ever needs a newer rustc, copy the `nixpkgs-rust195` input pattern already used for `pdfcraft`
(see the `flake.nix` header comments).
## 9. Pre-existing issues found (not blockers)
1. `packages.x86_64-darwin` **evaluates to an error**: `error: Nixpkgs 26.11 has dropped
support for x86_64-darwin.` Consequently `nix flake show --all-systems` and
`nix flake check`-style whole-system traversals can fail on that system. Unrelated to this
bump; affects every package in the repo.
2. `nix.conf` typo `sandbox_extra_readonly_paths = /home/minde/.beads` emits a warning on every
nix invocation.
3. `devShells` is empty, so AGENTS.md's `nix develop` instruction is stale.
4. `treefmt.toml` is unused by `nix fmt` (§7).
5. `nix flake show`/`nix eval` on `git+file:.` prints
`warning: Fetching Git repository 'file:.', which uses a path relative to the current
directory. This is not supported and will stop working in a future release.`
(nix issue 12281) — use an absolute path (`git+file:///home/minder/GIT/millerson.name/nix-overlay`)
to silence it.
## 10. One-line answers
| question | answer |
|---|---|
| nix installed + flakes? | **Yes** — nix 2.34.9, `experimental-features = nix-command flakes` (system `nix.conf`); no flag needed |
| nix-update? | **Not on PATH**; `nix shell nixpkgs#nix-update` → 1.15.1 (works, verified end-to-end) |
| nix-prefetch-git / -github / prefetch-git / nix-prefetch? | **All missing**; first two installable from cache; `nix-prefetch-url` **is** present; `prefetch-git`/`nix-prefetch` don't exist |
| network? | **Yes** — GitHub API/atom/codeload and nix caches reachable; fixed-output sandbox builds get network (proven) |
| attribute name | **`marmel`** (i.e. `packages.x86_64-linux.marmel`); also on `aarch64-linux` + `aarch64-darwin`; `x86_64-darwin` is broken upstream |
| recommended command | `nix shell nixpkgs#nix-update --command nix-update --flake --version=branch=main marmel` |
| fallback | manual `rev` + `nix-prefetch-url --unpack`/`fetchFromGitHub hash=""` for `src.hash`, then `nix build .#marmel`'s `vendor-staging` hash-mismatch for `cargoHash` (§6) |
| sandbox permits it? | **Yes** — no `__noChroot` needed and none used; `--option sandbox false` is a no-op for this untrusted user |
| formatting | `nix fmt packages/marmel/package.nix` (treefmt wrapper → nixfmt 1.5.0); nix-update's output is already clean |