---
spec: nix-flake-packaging
blocked-by: 0001-flake-build
---

## What to build

The remaining flake outputs layered onto the working build: a runnable app, a development shell, direnv auto-loading, and a checks set that gates the project reproducibly.

The default app points at the compiled binary so the CLI runs without a prior install.
The default dev shell exposes the same pinned Bun as the build plus biome, and a `use flake` direnv configuration loads it automatically on entering the directory.
The checks set aggregates the Bun test tiers, a build-seam smoke check that invokes the built binary (for example `--help`) and asserts a zero exit, and biome lint run through the treefmt-nix flake-parts module sharing the existing biome configuration.

## Acceptance criteria

- [x] `nix run` executes the CLI without a prior install.
- [x] `nix develop` drops into a shell exposing the pinned Bun and biome at their expected versions.
- [x] The dev shell's Bun version is the same pin the build derivation uses.
- [x] A `use flake` `.envrc` auto-loads the dev shell for direnv users.
- [x] `nix flake check` runs the Bun test tiers, the build-seam smoke check against the Nix-built binary, and biome lint via treefmt-nix.

## Implementation Notes

All five criteria were verified end-to-end: `nix run` exits 0, `nix develop` exposes Bun 1.3.13, biome 2.5.4, and bun2nix, and `nix flake check` runs all three checks green.

### Outputs

The default app points at the compiled binary via its store path.
The dev shell carries the pinned Bun, biome, and bun2nix — bun2nix so the repo's `postinstall` regeneration of `bun.nix` works inside the shell.
`.envrc` is a one-line `use flake`, and `.direnv/` is gitignored.

### Bun pin sameness

The dev shell takes Bun from `inputs.nixpkgs-bun` directly, while the build takes it through bun2nix, whose nixpkgs `follows` the same `nixpkgs-bun`.
Both therefore resolve to the one pinned input, which is the single source of the Bun version.
The value is not threaded through a shared binding because bun2nix bakes its own `pkgs.bun` into its build hook, so the compile-side Bun cannot be passed in — the shared `nixpkgs-bun` input is the seam instead.

### Checks

`tests` runs `bun test` across the workspace through bun2nix's check phase.
`smoke` runs the Nix-built binary with `--help` and asserts a zero exit; while the CLI is still a placeholder this passes for any argument, and it will exercise real `--help` once the CLI lands.
Biome runs through the treefmt-nix flake-parts module, which auto-adds its own check.

### Biome via treefmt-nix

The treefmt biome program reads the repo's `biome.json` (via `importJSON`) so there is one configuration, but with `vcs.enabled` overridden off: the reproducible check has no git tree, and biome's `useIgnoreFile` lookup errors without one, while treefmt already selects the files.
Schema validation is skipped because nixpkgs' biome is newer than the schema treefmt-nix would validate against, and the config is the one biome itself runs with.

### Deviation

`packages/core/src/index_test.ts` was reformatted by biome (two `test.todo` lines exceeded the repo's `lineWidth`).
This is a pre-existing file, formatted only to make the new lint gate green — a necessary consequence of adding the gate, not a change of its behaviour.