bundlewrap/bundles/AGENTS.md

bundles/

Before you start

Read docs/agents/conventions.md first — it covers vault calls, demagify, the repo.libs.<x> helpers, and the files agents must not modify. Skipping it leads to subtly broken bundles (vault calls in the wrong place, dict-in-set TypeError because of unhashable nesting, etc.).

For bundlewrap-language reference (item types, dep keywords, metadata_reactor, defaults, item-file template syntax) see the fork's AGENTS.md and its docs/content/guide/item_file_templates.md.

What's here

103 bundles. Each is a directory bundles/<name>/ containing some of:

bundles/<name>/
├── items.py        # the items this bundle creates (files, services, packages, …)
├── metadata.py     # `defaults` + `@metadata_reactor` functions
├── files/          # static or templated file payloads referenced from items.py
├── AGENTS.md       # this bundle's doc (template at AGENTS.template.md)
└── README.md       # legacy; being phased out (see "Documentation transition" below)

Conventions

• Bundle names are lowercase, hyphen-separated: backup-server, bind-acme, dm-crypt. No underscores in new bundle names — see conventions.md#naming-conventions.
• items.py is plain Python; it produces files = {...}, pkg_apt = {...}, svc_systemd = {...}, etc. dicts at module scope. Cross-item dependencies use needs / triggers / triggered_by — see the fork's AGENTS.md for the full keyword cheat sheet.
• metadata.py uses defaults = {...} for static seed values and @metadata_reactor.provides(...) for derived values. Reactors are pure functions of (metadata,) — no side effects, no I/O.
• Helpers go in libs/ when they're useful to more than one bundle. Don't duplicate logic across bundles.
• Custom item types (e.g. download:) live in items/, not per-bundle.

How to add a new bundle

1. mkdir bundles/<name>/ (lowercase, hyphenated).
2. Write items.py and (if anything is configurable) metadata.py. Use repo.libs.hashable.hashable(...) when you need to nest a dict or set inside a metadata set; raw dicts/sets aren't hashable.
3. Drop static payloads into bundles/<name>/files/. For Mako-templated files, declare 'content_type': 'mako' on the file: item — see the fork's item-file-templates guide.
4. Wire to nodes. Either add an entry to the relevant groups/<axis>/<x>.py (preferred for shared bundles) or to the node's bundles list directly (nodes/AGENTS.md).
5. Verify, in this order:
   • bw test — sanity (loaders + reactors).
   • bw items <node> — confirm new items appear on a node that opts in.
   • bw hash <node> — confirm the change is what you expected. See docs/agents/commands.md and the fork's hash-diff workflow.
6. Create bundles/<name>/AGENTS.md from AGENTS.template.md. For a brand-new bundle without consumers yet, leave Depends on and Produces empty or marked TBD; fill them in after the first verify run.

How to remove a bundle

1. git grep '<name>' in nodes/, groups/, and other bundles/ to find references.
2. Remove those references.
3. rm -rf bundles/<name>/.
4. bw test and bw nodes to confirm clean.

Pitfalls

• metadata.py is evaluated at load time for every node, every invocation of bw. Heavy work or I/O slows the whole repo. Keep reactors pure and fast; pre-compute in libs/ if you must.
• Static files vs templates. bundles/<x>/files/<f> is static unless the matching file: item declares content_type='mako' (or a templating extension triggers it). To check, read the matching file: entry in items.py.
• Reactors writing across namespaces. Some bundles' reactors write into other bundles' metadata namespaces (e.g. nextcloud writes into apt.packages, archive.paths). When you change such a bundle, every consumer's metadata changes too. Per-bundle docs declare these in an optional ## Writes into section — read it before assuming the blast radius is local.
• bw hash doesn't accept selectors. Use bw hash <node> per literal name; see the fork's runbook.

Documentation transition

This repo is migrating from bundle README.md files to per-bundle AGENTS.md files (one balanced doc per bundle, agents + humans).

• Where both exist, AGENTS.md is canonical; the README.md is being phased out.
• ~28 bundle READMEs survive after the seed migration (the seed PR folds in 5–10 of them; the rest are addressed lazily on the next material edit — Phase 3 leave-as-you-go).
• Phase-3 rule: any time you (or any agent) materially edits a bundle, top-up its AGENTS.md or create one from AGENTS.template.md. If a stale README.md is still around in the bundle, fold it in and remove it in the same commit.

See also

• AGENTS.template.md — per-bundle doc template.
• docs/agents/conventions.md — repo idioms (vault, demagify, naming, do-not-touch list).
• docs/agents/commands.md — repo-specific command deltas.
• items/AGENTS.md — custom item types (download:); when to write a new one vs use file:.
• libs/AGENTS.md — shared helpers.
• Fork's AGENTS.md — bundlewrap-language reference + safety envelope.