Build & Setup¶
VS Code setup¶
Install these extensions for a productive experience:
| Extension | ID | Purpose |
|---|---|---|
| Zig Language | ziglang.vscode-zig |
Zig language, Syntax highlighting, ZLS integration, build tasks |
| Rainbow CSV | mechatroner.rainbow-csv |
Column-aware CSV viewer - helpful when reading source exports |
| JSON5 | blueglassblock.better-json5 |
Syntax highlighting for JSON5 config files |
| Mermaid preview | bierner.markdown-mermaid |
Renders Mermaid diagrams in Markdown preview (useful for architecture/) |
| Mermaid syntax | bpruitt-goddard.mermaid-markdown-syntax-highlighting |
Syntax highlighting for Mermaid diagrams (useful for architecture/) |
ZLS (Zig Language Server) and Zig language are bundled with the ziglang.vscode-zig extension - it provides completions, go-to-definition and inline error diagnostics out of the box.
Verify Zig language version¶
The required Zig version is pinned in build.zig.zon (minimum_zig_version) —
install that toolchain; ZLS bundled with the Zig extension matches it.
bxp-core has three external (fetch) dependencies — uucode (MIT), the
Unicode case-mapping tables behind UPPER/LOWER; regex
(quangd/regex.zig, Apache-2.0 OR MIT), the Pike-VM engine behind
REGEX_MATCH/REGEX_EXTRACT (linear-time, ReDoS-safe); and zig_libs (MIT),
supplying 12 modules — the whole primitive layer: the datefmt date core,
the tz IANA offset lookup, the encoding code-page transcoder, the json5
preprocessor, the decimal fixed-point numeric core, the numparse grouped-
number parser, the zipstream ZIP reader, the csvstream CSV reader, the
diagnostics collector, plus minisign and procrun (re-exported for
bxp-gui-bridge) and mcp (the JSON-RPC transport re-exported for bxp-mcp).
All are pinned in bxp-core/build.zig.zon. The
fetches are cached after the first build; CI runners have network.
In VS Code terminal:
Claude Code setup¶
BXP development in Zig works seamlessly with Claude Code.
The monorepo ships eight CLAUDE.md files — root, bxp-cli/, bxp-core/,
bxp-mcp/, bxp-gui/, bxp-gui-bridge/, bxp-gui/packages/json5_ast/, and
docs/examples/ — Claude loads these automatically and reads project conventions.
Skills to use¶
The zig API-reference skill (targets Zig 0.16.0) ships with this repo's Claude
Code setup; see the root CLAUDE.md for the skill conventions.
| Skill | When to use |
|---|---|
/zig |
Before writing any new Zig code - loads Zig 0.16.0 API patterns |
/zig-build |
Compile the project and get structured error analysis |
/zig-check |
Fast syntax/type check without full build |
/zig-test |
Run the test suite and analyze failures |
Repository layout¶
Generated by walking the repository, with each entry's note read from the
file's own header — a //! line in Zig, the comment under a script's
shebang, the description: front matter of a Markdown page. Directories are
described in the generator's own catalog. Nothing here is retyped, so a new
file arrives on this page with the commit that adds it.
bxp/ # monorepo root (git root)
├── bxp-cli/ # user-facing CLI binary — the conversion engine
│ ├── src/ # arg parsing, config dispatch, the processing pipeline
│ │ ├── cli_docs.zig # Co-located documentation catalogs for bxp-cli's CLI surface: the flag table (the `--help` renderer's source) and the process exit codes
│ │ ├── main.zig # Broker eXchange Parser — CLI entry point
│ │ └── pipeline.zig # Processing pipeline for bxp-cli: per-template file conversion and xlsx pre-pass
│ ├── CLAUDE.md
│ ├── build.zig
│ └── build.zig.zon
├── bxp-core/ # internal shared library (no binary of its own)
│ ├── src/ # the domain layer: parsers, evaluator, config, trace, inspect
│ │ ├── btrace.zig # Binary trace stream — compact metadata emitted by `bxp-cli --trace`
│ │ ├── config.zig # Configuration types and JSON loader for bxp
│ │ ├── docs.zig # Aggregates and serializes the documentation surface `inspect.docsJson` exposes to the GUI, and renders the Markdown reference tables
│ │ ├── expr.zig # Expression evaluator used to compute input_schema variable values
│ │ ├── inspect.zig # inspect — shared stateless inspection core for bxp-mcp and the GUI bridge
│ │ ├── json.zig # Streaming JSON array-of-objects reader for bxp-cli
│ │ ├── module_docs.zig # Architecture catalogs for bxp-core: the module inventory and the stateless `inspect` surface
│ │ ├── unicode.zig # In-house Unicode text operations for expr.zig builtins
│ │ ├── wasm.zig # wasm32 export wrapper around the stateless inspect core
│ │ └── xlsx.zig # Converts Excel .xlsx workbooks to CSV
│ ├── CLAUDE.md
│ ├── build.zig
│ └── build.zig.zon
├── bxp-mcp/ # MCP server (JSON-RPC 2.0 over stdio) for AI agents
│ ├── src/ # entry point, tool catalog, bxp_simulate orchestration
│ │ ├── main.zig # bxp-mcp — entry point
│ │ ├── sim.zig # bxp-mcp — bxp_simulate orchestration
│ │ └── tools.zig # bxp-mcp — tool catalog + handlers (in-process, no spawn)
│ ├── CLAUDE.md
│ ├── build.zig
│ └── build.zig.zon
├── bxp-gui/ # Flutter desktop app (Linux / macOS / Windows)
│ ├── fonts/ # the bundled UI font, embedded rather than fetched at runtime
│ ├── installer/ # NSIS script for the Windows installer
│ ├── lib/ # Dart source: services (FFI + prefs + updater), store, ui
│ ├── linux/ # Linux Flutter shell + CMake hooks
│ ├── macos/ # macOS Flutter shell
│ ├── packages/ # path-dep Dart packages — today just json5_ast
│ ├── test/ # widget + unit tests, incl. the cross-runner expression corpus
│ ├── tool/ # developer probes, e.g. the Windows bridge stream check
│ ├── web/ # web Flutter shell (not shipped; keeps `flutter` happy)
│ ├── windows/ # Windows Flutter shell
│ ├── CHANGELOG.md
│ ├── CLAUDE.md
│ ├── README.md
│ ├── analysis_options.yaml
│ ├── devtools_options.yaml
│ └── pubspec.yaml
├── bxp-gui-bridge/ # Zig FFI shared library — the GUI's single backend
│ ├── src/ # C-ABI exports and the marshalling around them
│ │ ├── main.zig # bxp-gui-bridge — Dart FFI shim that proxies bxp-core inspect ops / bxp-cli calls
│ │ └── ops.zig # Catalog of the bridge's C-ABI surface
│ ├── test/ # re-exec helper binary driving the subprocess tests
│ │ └── test_helper.zig # bridge-test-helper — controllable child process for bridge unit tests
│ ├── CLAUDE.md
│ ├── build.zig
│ └── build.zig.zon
├── tools/ # build-time documentation generators (never distributed)
│ ├── dart-doc-gen/ # renders the Dart GuiToolDoc pages (runs as a flutter test)
│ └── zig-doc-gen/ # renders every Zig catalog and @typeInfo page into docs/
├── datasets/ # anonymized sample data + expected output, gated by test-07
├── docs/ # the MkDocs site — this documentation
│ ├── ai/ # agent-facing guides: authoring a broker, gui-mcp, handoff
│ ├── assets/ # site assets: stylesheets, the playground JS, the wasm engine
│ ├── dev/ # developer documentation: build, test, debug, architecture, release
│ ├── examples/ # the runnable example tree plus its Examples section pages
│ ├── getting-started/ # install, first conversion, the shipped template library
│ ├── gui/ # bxp-gui user guide: features, preferences, updates, troubleshooting
│ ├── guide/ # user guide: templates, expressions, dates, routing, targets
│ ├── includes/ # generated fragments pulled into hand-written pages
│ ├── reference/ # generated reference pages — do not edit by hand
│ └── index.md # Convert tabular exports — CSV, XLSX or JSON — into the shape another tool expects, with declarative JSON5 templates and no code
├── resources/ # files shipped inside the release archives
│ ├── console/ # the sample config bundled with the console archives
│ ├── desktop/ # the Linux launcher template bundled with the desktop archives
│ └── icons/ # SVG variants + build-icons.sh, the single source for app icons
├── scripts/ # test, release and documentation tooling
│ ├── bench/ # developer-only benchmark matrix (not part of test.sh)
│ │ ├── results/ # recorded benchmark runs — the baseline a regression is measured against
│ │ ├── bench.sh # BXP stress-test matrix runner
│ │ ├── gen-xlsx.py # Synthetic .xlsx generator for profiling bxp-core/src/xlsx.zig ingest
│ │ ├── gen.py # Generate synthetic input.in.csv + bxp-cli.json for a single bench run
│ │ ├── verify-output.sh # One-off output verification for the chunking refactor
│ │ ├── xlsx-bench.json
│ │ └── xlsx-fanout-bench.json
│ ├── docs/ # documentation support: site generation, wasm playground, checks
│ │ ├── mermaid-check/ # the mermaid-fence parser behind check-formatting.sh
│ │ ├── check-formatting.sh # Documentation mermaid check — PRE-RELEASE ONLY
│ │ ├── check-wasm-parity.py # Compare the wasm and native expression evaluators over the shared corpus
│ │ ├── check-wasm-parity.sh # wasm/native parity gate for the docs expression scratchpad
│ │ ├── gen-docs.sh # Generate the MkDocs documentation site and (default) serve it locally
│ │ ├── gen-examples-index.py # Generate the Examples index pages for the MkDocs site
│ │ ├── gen-trees.py # Generate the repository-layout tree and the test-phase list for the docs
│ │ ├── gen-wasm-playground.sh # Build the docs playground's wasm engine into docs/assets/wasm/
│ │ └── requirements.txt
│ ├── README.md
│ ├── release-01-console.sh # Build console release archives for Linux, Windows, and macOS
│ ├── release-02-desktop.sh # Build the bxp-desktop release bundle for the current host OS
│ ├── release-03-checksums.sh # Generate (or verify) SHA256SUMS for the release artifacts in a dir tree
│ ├── release-changelog.sh # Bump versions across all 6 manifests + generate a CHANGELOG.md entry from commits since the last release tag, in one step
│ ├── release-tag.sh # Cut a release tag from the version already written into the manifests by `release-changelog.sh`, and push it
│ ├── release.sh # Run the local release-build flow
│ ├── test-01-console.sh # Console-side build + unit tests (bxp-core, bxp-cli, json5_ast)
│ ├── test-02-mcp.sh # bxp-mcp build + unit tests + JSON-RPC smoke
│ ├── test-03-bridge.sh # bxp-gui-bridge unit tests
│ ├── test-04-desktop.sh # Desktop-side tests: the Flutter app and the embedded json5_ast package
│ ├── test-05-bench-guard.sh # Performance regression guard
│ ├── test-06-expr-corpus.sh # Expression corpus regression gate
│ ├── test-06-expr-corpus.txt
│ ├── test-07-datasets.sh # Dataset regression: run bxp-cli against every datasets/<template>/sample.json and diff every generated *.csvx against the matching *.expected fixture
│ ├── test-08-docs-examples.py # Checker behind scripts/test-08-docs-examples.sh — see that script's header
│ ├── test-08-docs-examples.sh # Docs example-page gate: the clickable expressions must actually work
│ ├── test-09-examples.sh # Example regression: run bxp-cli against every docs/examples/<tier>/<name>/ sample.json and diff each produced output against its committed *.expected golden
│ ├── test-lib.sh # Sourced; not executable on its own
│ └── test.sh # Run the full test suite
├── .github/ # CI configuration
│ ├── ISSUE_TEMPLATE/ # GitHub issue forms
│ ├── workflows/ # the CI, docs-publish and release pipelines
│ └── PULL_REQUEST_TEMPLATE.md
├── README.md
├── CHANGELOG.md
├── CONTRIBUTING.md
├── SECURITY.md
├── CODE_OF_CONDUCT.md
├── LICENSE.md
├── CLAUDE.md
└── mkdocs.yml
Clone and build¶
# Clone this repository
git clone https://github.com/zaxified/bxp.git
# Build bxp-cli (fetches dependencies on first run)
cd ./bxp/bxp-cli
zig build
# Run
./zig-out/bin/bxp-cli --help
Running bxp-cli without arguments processes every template defined in bxp-cli.json
in the current working directory. \
The typical dev workflow:
# From the monorepo root
./bxp-cli/zig-out/bin/bxp-cli --config ./datasets/anycoin_to_wealthfolio/sample.json --debug
The wasm playground target¶
bxp-core also builds for wasm32-freestanding, which is what powers the
clickable expressions on the docs site — the reader's browser runs bxp's own
evaluator rather than a JavaScript re-implementation. It is an opt-in target,
never part of install:
In practice you do not run that by hand: scripts/docs/gen-wasm-playground.sh builds
it into docs/assets/wasm/bxp-eval.wasm, and scripts/docs/gen-docs.sh calls that
script for you. The .wasm is a build artifact and stays untracked — a checkout
regenerates it, and a docs build without it leaves the panel reporting that it
could not load the engine.
Agreement with the native engine is measured rather than assumed:
scripts/docs/check-wasm-parity.sh runs the cross-runner expression corpus through
both and requires byte-identical results. It needs a JS runtime, so it is a
docs-workflow step rather than a test-NN phase.
Run the test suite¶
Seven phases covering Zig unit tests, MCP smoke, bridge, Flutter, perf guard, expression corpus, and dataset regression. See Testing for the full phase breakdown, individual sub-suite commands, and how to add regression tests.