Development

Repo layout

Path	Content
`src/main.py`	Entry point; signal handlers stop running containers on Ctrl-C.
`src/commands/__init__.py`	Command tree engine: nested dict (`_help`, `_handler`, `_args`) → argparse subparsers; unique-prefix abbreviation; version-mismatch dispatch.
`src/commands/common/`	`create`, `gui`, `login`/`logout`, `upgrade`, `info project`/`secrets`, `configure project`.
`src/commands/hive_s/`, `src/commands/hive_m/`	Template command sets.
`src/commands/hive_m/common/__init__.py`	Init script prepended to every hive-m container run.
`src/project.py`	Project load/save/create, Docker image build, container/volume orchestration.
`src/state.py`	Docker client plus the running container/process handles the Ctrl-C handler stops.
`src/common.py`	Template copy, hash manifest, baseline, `smart_update` (3-way merge).
`src/models/`	Pydantic models for `project.json`.
`src/validate.py`	Argument validation: project names, module names, file paths.
`src/log.py`	Console output with the `INFO:`/`WARNING:`/`ERROR:`/`OK:` prefixes the GUI colors by.
`src/vault.py`	Secrets server client: OIDC login, token cache, secret lookup.
`src/signing.py`	Buildsign client.
`src/selfupdate.py`	Release lookup on GitHub, installer download and start (`upgrade`, GUI update button).
`src/constants.py`	`VERSION`, container constants, `SECRETS_URL`, `SDK_IMAGE`.
`src/templates/`	`default` (shared skeleton), `hive-s`, `hive-m` project templates.
`src/gui/`	PySide6 GUI, see gui.md.
`src/layerconf.py`, `src/recipe_index.py`, `src/scripts/recipe_indexer.py`	`IMAGE_INSTALL:append` editing and the recipe index (`packages` commands). `recipe_indexer.py` is shipped as a data file and run with python3 inside the container.
`tests/`	pytest suite, no Docker needed: `python -m pytest tests`.
`tools/gui_screenshots.py`	Renders `docs/images/gui/*.png` for the GUI docs.
`docs/`	mdBook sources (`book.toml`, `SUMMARY.md`), published to GitHub Pages.
`buildhive.spec`	PyInstaller spec, one analysis, two exes (`buildhive.exe`, `buildhive-gui.exe`).
`setup.iss`	Inno Setup installer script.
`dist/`	PyInstaller output + `BuildHive_Setup.exe`.

Release process

The version lives in one place: src/constants.py (VERSION). Everything else derives from it:

setup.iss parses it at compile time (ISPP reads the first line of constants.py).
Hive-M containers export it as BUILDHIVE_VERSION through BB_ENV_PASSTHROUGH_ADDITIONS; update-archive.bb and legacy-migration-update.bb default UPDATE_VERSION/MIGRATION_VERSION from it (fallback 0.0.0 for manual bitbake).
project.json buildhive_version is stamped on save; a mismatch with the running tool triggers the update flow.
upgrade and the GUI compare it against the newest GitHub release tag.

Release:

Bump VERSION in src/constants.py.
make build (PyInstaller, dist/buildhive/), then compile setup.iss → dist/BuildHive_Setup.exe.
GitHub release in NetTimeLogic/Tools: tag buildhive_v<x.y.z>, asset uploaded as BuildHive_<x.y.z>_Setup.exe. Drafts and pre-releases are ignored by the update check; the asset name must match BuildHive_*_Setup.exe.

The installer (setup.iss) installs per user into %APPDATA%\NTL\BuildHive\bin, no admin. Same AppId on every version: Setup replaces the uninstall entry itself and deletes the old bin/ before copying, so an upgrade needs no separate uninstall. The upgrade command starts the downloaded installer two seconds after the CLI exits so bin/ is not in use. Uninstall removes the PATH entry and the app directory.

Documentation

docs/ is an mdBook. README.md is the front page: the workflow copies it to docs/README.md with docs/ stripped from its links (docs/README.md and docs/book/ are gitignored). Build locally:

sed 's#](docs/#](#g' README.md > docs/README.md
mdbook build docs      # or: mdbook serve docs

.github/workflows/buildhive-docs.yml builds on every push to master touching buildhive/docs/** or buildhive/README.md and deploys to GitHub Pages (repository setting Pages > Source: GitHub Actions). New pages go into docs/SUMMARY.md.

GUI screenshots: python tools/gui_screenshots.py on a desktop session, no Docker needed. Rerun after visible GUI changes.

Template update mechanism

State per project: .buildhive_manifest.json (SHA-256 of every template file at last sync) and .buildhive_baseline/ (pristine text-file copies).

On version mismatch where the project is older than the tool, the user is prompted to update. Per file, three hashes decide (old manifest, new template, current disk):

Situation	Action
Template unchanged, user changed	keep user file
Template changed, user unchanged	overwrite (backup `.bak`)
Both changed	3-way merge via `git merge-file` against the baseline; conflicts get git-style markers
Unmergeable (binary / no baseline)	prompt: keep yours / take template
File removed from template	kept on disk, reported
New template file	copied in

images/ and project.json are never touched. Unresolved conflicts keep their old manifest hash, so they are re-prompted on the next update. buildhive_version is bumped only after all conflicts are resolved - an aborted update prompts again.

If the project is newer than the tool, no files are modified; the tool asks you to upgrade BuildHive.

Template edits during development: hive-m copies sw/meta-ntl-hive into the Yocto build tree on every container start, so layer changes in a project take effect on the next build without any sync step. Changes to src/templates/ reach existing projects only through the version-mismatch update flow.