Hexalith.Builds

Common build, release, and repository automation assets for Hexalith applications, modules, and libraries.

Overview

This repository centralizes the shared build configuration used across the Hexalith ecosystem. It provides MSBuild properties, analyzer configuration, central package versions, GitHub composite actions, reusable workflows, release configuration, and repository maintenance tools.

This repository:

• Centralizes package version management for consuming repositories.
• Provides common MSBuild settings for .NET projects and NuGet packages.
• Enforces shared analyzer, code style, nullable, and documentation settings.
• Provides reusable GitHub Actions for verification, release, Dapr bootstrap, and container deployment.
• Provides semantic-release configuration for Conventional Commit based releases.
• Keeps AI assistant instructions and repository conventions discoverable.

Repository Structure

Build Configuration

• Hexalith.Build.props: Common MSBuild properties, analyzers, source link, nullable, documentation, and package version settings.
• Hexalith.Package.props: NuGet package metadata and package build settings for library projects.
• Props/Environment.Build.props: CI and IDE build detection.
• Props/Directory.Packages.props: Central package versions for Hexalith projects.
• Samples/Module.Directory.Build.props: Sample module root Directory.Build.props.
• Samples/Module.Directory.Packages.props: Sample module Directory.Packages.props.

Release Configuration

• package.json: semantic-release configuration for this repository.
• package-lock.json: Locked npm dependency graph for reproducible release jobs.
• Github/package-release/release.config.json: Shared semantic-release config for package-producing repositories (legacy — domain modules use domain-release.yml with a module .releaserc.json).
• Github/scripts/build-packages.ps1: Builds library projects during semantic-release.
• Github/scripts/publish-packages.ps1: Publishes each primary NuGet package once during semantic-release; dotnet publishes its adjacent symbols package.

Code Style and Analysis

• .editorconfig: Shared editor and analyzer style settings.
• Hexalith.globalconfig: Global C# analyzer configuration.
• stylecop.json: StyleCop configuration.

AI Assistant Rules

• AGENTS.md, CLAUDE.md, and .github/copilot-instructions.md: the shared, location-independent baseline for Codex, Claude, and GitHub Copilot.
• DEVELOPMENT.md: repository-specific Build, release, and C# development guidance.

Tools

• Tools/: Repository utility scripts.
  • builds-submodule-init.ps1: Adds or initializes the Hexalith.Builds submodule under references/ and checks it out on main.
  • editorconfig-symlink.ps1: Creates a parent repository .editorconfig symlink pointing to references/Hexalith.Builds/.editorconfig.

GitHub Composite Actions

• Github/create-release/: Run semantic-release without hard-coding package behavior; repositories may configure their own verified package lifecycle (legacy — modules use domain-release.yml).
• Github/dapr-init/: Install the Dapr CLI and run dapr init with retry.
• Github/governed-provenance/: Validate the running job's reusable-workflow identity and emit the bounded static uses:-closure provenance the governed BUILD-REL-1 paths in domain-ci.yml and domain-release.yml hand to their callers.
• Github/initialize-build/: Initialize root-declared submodules without recursive or remote updates.
• Github/initialize-dotnet/: Install the .NET SDK from global.json or an explicit version, with optional Aspire workload installation.
• Github/package-release/: Build and release package projects with semantic-release (legacy — modules use domain-release.yml).
• Github/publish-azure-container-app/: Update Azure Container Apps to a published image version (legacy HexalithApp-era).
• Github/publish-container-to-registry/: Build and publish Web/API containers to a registry (legacy — modules use domain-release.yml container publishing).
• Github/publish-containers/: Install the semantic-release container publish helper used by domain-release.yml.
• Github/unit-tests/: Run and clean a standard Hexalith test project (legacy — modules use domain-ci.yml).
• Github/verify/: CI gate that checks out, initializes, builds through tests, and does not publish (legacy — modules use domain-ci.yml).

Reusable Workflows

• .github/workflows/build-release.yml: Releases this repository with Github/create-release.
• .github/workflows/domain-ci.yml: Reusable domain module CI pipeline. See domain-ci.md.
• .github/workflows/domain-release.yml: Reusable domain module release pipeline. See domain-release.md.

Usage

Add Hexalith.Builds as a Submodule

From a consuming repository root, add or initialize this repository as a root-declared submodule under references/:

Invoke-WebRequest -Uri "https://raw.githubusercontent.com/Hexalith/Hexalith.Builds/main/Tools/builds-submodule-init.ps1" -OutFile "builds-submodule-init.ps1"
.\builds-submodule-init.ps1

After the submodule exists, the same script is available from the build submodule:

.\references\Hexalith.Builds\Tools\builds-submodule-init.ps1

The script requires administrator privileges on Windows because related tooling may create symbolic links. It initializes only the references/Hexalith.Builds submodule and checks out main.

Import Build Properties

Use the sample files in Samples/ as the starting point for consuming repositories. A typical module root Directory.Build.props imports the shared build props and then sets repository-specific package metadata:

<Project>
  <Import Project="references/Hexalith.Builds/Hexalith.Build.props"
          Condition="Exists('references/Hexalith.Builds/Hexalith.Build.props')" />

  <PropertyGroup>
    <Product>Hexalith.MyModule</Product>
    <RepositoryUrl>https://github.com/Hexalith/Hexalith.MyModule.git</RepositoryUrl>
    <PackageProjectUrl>https://github.com/Hexalith/Hexalith.MyModule</PackageProjectUrl>
    <PackageTags>hexalith;my module;</PackageTags>
    <Description>Hexalith MyModule Module</Description>
  </PropertyGroup>
</Project>

For library projects that should produce NuGet packages, import Hexalith.Package.props from the source-level Directory.Build.props:

<Project>
  <PropertyGroup>
    <ParentDirectoryBuildProps>$([MSBuild]::GetPathOfFileAbove('Directory.Build.props', '$(MSBuildThisFileDirectory)../'))</ParentDirectoryBuildProps>
  </PropertyGroup>

  <Import Project="$(ParentDirectoryBuildProps)"
          Condition="Exists('$(ParentDirectoryBuildProps)')" />

  <Import Project="../references/Hexalith.Builds/Hexalith.Package.props"
          Condition="Exists('../references/Hexalith.Builds/Hexalith.Package.props')" />
</Project>

Import Central Package Versions

Props/Directory.Packages.props is the sole NuGet package-reference version authority for Hexalith repositories. A consumer-root Directory.Packages.props is a version-free wrapper: it imports the shared catalog and may retain only non-version CPM settings such as its existing transitive-pinning posture.

<Project>
  <Import Project="references/Hexalith.Builds/Props/Directory.Packages.props"
          Condition="Exists('references/Hexalith.Builds/Props/Directory.Packages.props')" />
</Project>

Do not add consumer PackageVersion items, dependency-version properties, PackageReference Version or VersionOverride metadata, or a CPM opt-out. Add a missing dependency to the shared catalog through a reviewed Builds change, then keep the consuming PackageReference version-free. MSBuild project SDK pins and local tool-manifest pins cannot use CPM; they must be recorded in Tools/package-version-exceptions.json and pass its alignment validator.

Run the catalog, consumer, and exception validators documented in Tools/README.md before integrating a catalog or wrapper change.

G-4 Local Tools

This repository owns two repository-scoped .NET tools. They are the only public runner and readiness-validator contracts for the G-4 workflow:

Package ID	Tool command	Purpose
Hexalith.Builds.Module.Cli	hexalith-module	Validates a module manifest and owns supported runner lifecycle.
Hexalith.Builds.Evidence.Cli	hexalith-evidence	Validates hexalith.readiness-evidence.v1 matrices.

After an approved version is published, a consumer pins both exact versions in its checked-in .config/dotnet-tools.json, then restores and invokes them from the consumer checkout:

dotnet tool restore
dotnet tool run hexalith-module run --manifest module/hexalith-projects.module.json
dotnet tool run hexalith-module down --manifest module/hexalith-projects.module.json
dotnet tool run hexalith-module test --manifest module/hexalith-projects.module.json --profile full
dotnet tool run hexalith-evidence validate _bmad-output/planning-artifacts/implementation-readiness-traceability-matrix.yaml

An exact-version consumer manifest is intentionally not checked in before the first package is published; consumers must not invent a 4.20.0 pin. The semantic-release version and package hashes are the release record.

Pre-release consumers configure the Hexalith GitHub Packages NuGet source and authenticated package-read access outside the checked-in tool manifest; stable consumers restore from NuGet.org. Keep those credentials in user or CI NuGet configuration/secret storage, never in a module manifest, filter, or retained evidence artifact.

Module Manifest and Runner Contract

hexalith-module accepts a strict hexalith.module-manifest.v1 JSON file. All descriptor, UI, and fixture paths are forward-slash, repository-relative paths. Validation rejects unknown or duplicate fields, duplicate identifiers, path escapes, placeholders, unreadable files, unsupported pins, malformed dependencies, and secret-bearing values before any lifecycle work.

The profile classes are pure-domain, host-contract, persisted-boundary, restart, two-instance, authenticated-browser, authenticated-cli, and authenticated-mcp. They define runner handoff contracts; they do not turn a product assertion into a runner-owned pass claim.

Use --output json for a machine-readable diagnostic, and --evidence <repository-relative>.json to atomically retain canonical hexalith.module-run-evidence.v1 metadata. Filter values are retained only as SHA-256 fingerprints. Evidence identifies volatile timestamps and run IDs so semantic comparisons remain deterministic.

The exit-code contract is stable: 0 success, 1 usage/manifest, 2 prerequisite unavailable, 3 topology/lifecycle, 4 product/test, 5 persisted state, 6 evidence schema/policy, and 130 cancellation. The first causal failure is retained; a later evidence-write failure cannot rewrite an earlier runner failure.

The native-report parser validates TRX counters emitted by both VSTest and Microsoft Testing Platform/xUnit v3. Missing or invalid reports, zero matching tests, all-skipped tests, and failed test counts are explicit non-passing product/test outcomes once a live test invocation supplies a report. Parser coverage alone is not persisted-runtime proof.

Live persisted composition remains explicitly unavailable while the separately owned G-6 Dapr runtime-to-SDK disposition is unresolved. That result is a non-passing prerequisite outcome, never a skipped or passing qualification. down remains idempotent and only removes runner-owned invocation metadata.

Evidence Validator Contract

hexalith-evidence validate <matrix.yaml> parses YAML with duplicate-key checking before strict schema and policy validation. Diagnostics are sorted by source, row, rule, field, location, and hint. The validator rejects an undeclared row status such as the currently unresolved blocked matrix status; it does not mutate a consumer-owned matrix or invent status semantics.

Rows that claim passed or failed execution must reference a readable, repository-relative JSON artifact with the declared hexalith.module-run-evidence.v1 schema and SHA-256. Future-path references remain valid for pending, blocked-external, and not-verified rows. The positive evidence fixture is a schema/validator contract sample only; it is not persisted-runtime acceptance evidence.

Metadata and Troubleshooting

Do not put bearer tokens, credentials, source payloads, raw environment dumps, or protected tenant/resource values in a manifest, filter, fixture, or retained artifact. The tools reject manifest secret-bearing values and avoid retaining raw filters. If a command returns 2, resolve the documented external prerequisite rather than treating the run as a pass. If a command returns 6, correct the evidence path, schema, hash, status declaration, or policy diagnostic and rerun it.

Environment Detection

The build properties set environment flags used by consuming projects:

• CIBuild: Set to true in GitHub Actions or Azure DevOps.
• IDEBuild: Set to true in Visual Studio, ReSharper, VS Code, or Cursor.

Version and Release Management

Releases are driven by semantic-release and Angular Conventional Commits. Release jobs analyze commits, calculate the next version, create a Git tag and GitHub release, and publish the configured tool or NuGet packages. They do not commit generated release files back to protected branches.

Domain modules release intentionally through a manually dispatched caller and the protected-environment reusable domain-release.yml workflow with a module-owned .releaserc.json. The legacy Github/package-release action and its release.config.json remain only for pre-domain-workflow repositories.

Package publishing behavior:

• Stable versions are published to NuGet.org with NUGET_API_KEY.
• Pre-release versions are published to GitHub Packages with GITHUB_TOKEN.
• Debug and non-release local builds receive a generated VersionSuffix from Hexalith.Package.props.

For domain modules, manually dispatch the module release caller only after its exact current main SHA has successful push CI, then approve the protected environment deployment. This Builds repository releases only through a manual dispatch from the exact current main tip and its protected production environment. Merging or pushing does not start a release.

License

This project is licensed under the MIT License. See LICENSE for details.