Build And Release

Build and Release

There are two independent things that get released out of this repository, on two independent version schemes:

What	Tag scheme	Source of truth
The hypha plugin itself	bare v<MAJOR.MINOR.PATCH>	.claude-plugin/marketplace.json, which pins the plugin to a specific tag
The hypha CLI (Hypha.Tools)	tools-v<MAJOR.MINOR.PATCH>	.claude-plugin/plugin.json's hyphaCliVersion field, which the SessionStart hook downloads

Both are driven by manually-dispatched GitHub Actions workflows, nothing releases on a push.

release.yml – releasing the CLI

Manually dispatched with a SemVer version input. Steps:

1. Validates the input is SemVer (via an environment variable, not ${{ }} interpolation, to avoid script injection); a - suffix marks it as a pre-release.
2. Sets up .NET 10, Python 3.12 and the spec-extract virtualenv (from a locked, wheels-only requirements file).
3. dotnet restore && dotnet test: the knowledge-regeneration determinism proof (see Developers Experience) must pass before anything ships.
4. dotnet packs the Hypha.Tools project into a dotnet-tool .nupkg.
5. Pushes it to NuGet, skipped gracefully with a notice if NUGET_API_KEY is not configured; the package is still attached to the GitHub release either way.
6. dotnet publishes self-contained, single-file builds for win-x64, linux-x64, osx-x64 and osx-arm64.
7. Smoke test: runs the freshly published linux-x64 binary through fetch --tag 2026-05 --no-specs then generate --tag 2026-05 --output <tmp>, and asserts at least 100 files were generated. 2026-05 is used because it is the same tag committed as the Hypha.MetamodelGen.Tests fixture, so it is known-good.
8. Generates THIRD-PARTY-NOTICES.txt via nuget-license for the transitive dependencies, plus a hand-appended .NET Runtime (MIT) credit, needed because the self-contained builds bundle the whole runtime.
9. Zips each platform's publish output (plus NOTICE, LICENSE, THIRD-PARTY-NOTICES.txt) into ReleaseBuilds/hypha-<version>-<rid>.zip and records a SHA-256 for each in RELEASE_NOTES.md.
10. Tags the commit tools-v<version> and pushes the tag.
11. Drafts a GitHub Release (softprops/action-gh-release, pinned to a commit SHA rather than a tag, since it holds a content-write token) attaching the zips, the .nupkg and the notices. The release is left as a draft, a human still publishes it.

hook-binaries.yml – building the SessionStart hook

Manually dispatched. Builds Hypha.Tools.Hook via NativeAOT on four native runners, one per target platform (win-x64, linux-x64, osx-x64, osx-arm64), because true cross-OS AOT publishing is not reliable, unlike release.yml's single-runner cross-publish for the self-contained CLI builds. It commits the resulting binaries into hooks/native/<rid>/ if they changed. This is the only compiled binary this repository commits, and deliberately lives outside hooks/bin//bin/, which .gitignore otherwise excludes at any depth. See Skills and Agents#the-sessionstart-hook for what the resulting binary does.

Cutting a release

1. Confirm dotnet test mycelium-hypha.sln and pytest (in tools/spec-extract) are green.
2. Dispatch release.yml with the new CLI version, if the CLI changed.
3. Dispatch hook-binaries.yml if Hypha.Tools.Hook changed, and commit the updated hooks/native/<rid>/ binaries.
4. Bump hyphaCliVersion in .claude-plugin/plugin.json if the CLI version moved.
5. Publish the draft GitHub Release from release.yml.
6. Tag the plugin itself v<MAJOR.MINOR.PATCH> and update .claude-plugin/marketplace.json's pinned ref if the plugin's own version changed.

Code quality

GitHub Actions also run build-test-sonar.yml on every push and pull request, see Developers Experience for what it checks.