Migration & v3 Breaking Changes

Upgrade ordering (read this first)

v3 manifests no longer contain generatedAt — identical source now produces a byte-identical chowbea.bus.json, which is what makes no-op syncs produce no PR. The catch: v2 CLIs reject v3 manifests with Malformed chowbea bus manifest: generatedAt must be a string. v3 reads v2 manifests fine.

So: upgrade every consumer to chowbea-axios@^3 before the backend deploys a v3-produced manifest. Frontends first, backend second.

Migrating a frontend repo

One commit, six steps:

1. npm i -D chowbea-axios@^3.0.0 (keep it a devDependency — the workflows' npx resolves the lockfile-pinned version from node_modules).

2. Add the pin keys to api.config.toml — keep your existing api_endpoint:

   spec_file = "openapi.json"
   
   [bus]              # only if you consume a type bus
   endpoint = "https://staging.example.com/.well-known/chowbea.json"
   file     = "chowbea.bus.json"

3. Create the pins: npx chowbea-axios sync (needs the stable endpoint reachable once).

4. Stop tracking generated output: npx chowbea-axios doctor --fix — untracks _generated/** (files stay on disk) and adds the _generated/ ignore rule. Add api.config.local.toml to .gitignore yourself — doctor doesn't manage that entry.

5. Swap the workflows: copy chowbea-sync.yml + chowbea-pinned-ci.yml from node_modules/chowbea-axios/templates/ into .github/workflows/, delete the old endpoint-based staleness check, and set the CHOWBEA_PR_TOKEN secret.

6. Commit everything — pins, config, gitignore, workflows, the untracked-files fallout — as one change. git status must show no _generated/ files.

Verify before pushing: npx chowbea-axios generate succeeds with the network off, a second sync reports unchanged, and chowbea-axios doctor reports healthy.

The other v3 behavior change

With both api_endpoint and spec_file set (rare outside pinned mode — the scaffold used to comment one out), bare fetch and watch now resolve to the endpoint, not the file. That's the pinned-mode dev loop working as designed: live commands prefer live sources; generate/diff/validate still prefer the pinned file. Configs with only one source set behave exactly as before.

Errors you might meet mid-migration