namebucket #

Random gift exchange draw tool.

Reads a JSON list of people, draws a fresh random assignment, and writes one sealed file per person plus a master mapping.

Input #

namebucket people.json — the input file is a bare JSON array of person objects:

[
  {"name": "alice", "noMatch": ["bob"]},
  {"name": "bob"}
]

• name is a string, required.
• noMatch is an array of strings, optional; omitted and null both mean "no exclusions".
• Exclusions are symmetric: if alice lists bob, neither direction of the pair is drawn.
• Names are exact, case-sensitive strings.

Example #

$ namebucket people.json

Output #

For N people, exactly N + 1 files are written to the current directory (or --output-dir DIR):

• <name>.txt per person — contains only that person's recipient, so alice.txt containing bob means alice gives to bob.
• mapping.json — the whole assignment as from/to pairs, sorted alphabetically by from, for the organizer to keep.

If no valid assignment exists, namebucket exits non-zero with an error and writes no files at all.

Web app #

namebucket serve runs a small web app for the same exchange, embedded in the same binary:

$ namebucket serve --addr :8080 --data-dir ./data

The organizer creates a bucket in the browser — name, participants, exclusion pairs — and receives two links: a share link for participants (each picks their name, confirms, and sees their recipient) and an admin link for the organizer (links, read-only setup, delete). Buckets are immutable and never expire; each lives as one JSON file in the data directory.

The frontend (SolidJS with Bulma CSS, built with Vite) is rebuilt with just web-build; nix build produces the complete binary.

Shipping changes #

just push pushes main to tangled. It refreshes npmDepsHash first and refuses to run with uncommitted work in @ — finish changes with jj commit (or jj new for an empty @), then just push.

npmDepsHash pins the npm fixed-output derivation and must match web/package-lock.json exactly; it changes whenever the lockfile does, and a stale hash fails homelab's build of the pinned revision. The refresh is automatic and verified — never hand-edit the hash. Then in homelab: nix flake update namebucket and just deploy.