Aller au contenu

Packaging & sharing

bfev is intended to be shareable with colleagues who may not have your exact setup. Two distribution layers:

1. Python package

Standard wheel via Hatchling:

uv build                       # produces dist/bfev-0.1.0-*.whl + sdist
uv pip install dist/bfev-0.1.0-*.whl

A colleague then needs only Python 3.11+ and the wheel:

pip install bfev-0.1.0-*.whl
bfev --version
bfev init my-first-client

This installs the CLI, contracts, logging, lockfile, audit, and the crosscheck-XLSX builder. It does not install Claude Code or any agent definitions — those come from the plugin.

2. Claude Code plugin

The plugin (plugin/) ships:

  • plugin.json — plugin manifest
  • agents/{orchestrator,collection,simulate,calculate,report}.md — agent definitions with frontmatter declaring allowed tools and reading the contract from bfev.contracts.for_agent("<name>")
  • skills/ — the four pipeline skills, vendored from ~/.claude/skills/ with paths cleaned (no hardcoded /mnt/...)

A colleague installs the plugin via:

/plugin add <repo-url-or-path>/plugin

Then their Claude Code sees agent:orchestrator etc.

3. Optional: Docker

For colleagues who can't install Quarto / openpyxl / fonts cleanly:

docker build -t bfev:0.1.0 .
docker run -v ~/bfev:/data -e BFEV_HOME=/data bfev:0.1.0 init my-client

The Dockerfile bundles Python, uv, Quarto, fonts, and the bfev package. It mounts $BFEV_HOME so client data stays on the host filesystem.

Confidentiality boundary

Client data must never end up in the package. Two safeguards:

  1. $BFEV_HOME defaults to ~/bfev, outside any git repo.
  2. Any project that does check bfev.toml into git must .gitignore the clients/ directory. The repo's own .gitignore does this.

The package ships only resources/ (the master taxonomy, regulatory anchors, EF tables). IPCC volumes are fetched separately via bfev fetch-ipcc — they're public but heavy.

Versioning

bfev follows semver. Breaking changes to:

  • contract input/output schemas
  • the directory layout
  • the lockfile schema

…bump the major version. Adding optional fields or new audit checks bumps the minor. Bug fixes bump the patch.

Every project's lockfile.yaml records the bfev version it was created with. A project initialised under bfev 0.x won't run under bfev 1.x without an explicit bfev upgrade.

Build the documentation

The portal is built with MkDocs Material (the FastAPI stack). Config is mkdocs.yml at the repo root; content lives under docs/.

uv pip install --python .venv-linux/bin/python "mkdocs-material>=9.5,<10"
mkdocs serve     # live reload on http://127.0.0.1:8000
mkdocs build     # static site into site/

The Dockerfile under docs/deploy/ runs mkdocs build and serves the result with nginx (see Héberger le portail).