Merge pull request #224 from Vulthil/chore/prepare-public-nuget-release

chore: prepare first public NuGet.org release (v1.0.0)

Author: Vulthil

.github/workflows/claude.yml

@@ -40,8 +40,9 @@ jobs:
           additional_permissions: |
             actions: read
 
-          # Optional: Give a custom prompt to Claude. If this is not specified, Claude will perform the instructions specified in the comment that tagged it.
-          prompt: 'Update the pull request description to include a summary of changes.'
+          # No prompt is set on purpose: Claude follows the instructions in the
+          # comment, review, or issue that tagged it (e.g. "@claude fix the build").
+          # Set `prompt:` only if you want every trigger to run one fixed instruction.
 
           # Optional: Add claude_args to customize behavior and configuration
           # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md

.github/workflows/codeql.yml

@@ -0,0 +1,46 @@
+name: CodeQL
+
+on:
+  workflow_dispatch:  
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    - cron: '32 4 * * 1' # weekly, Monday 04:32 UTC
+
+concurrency:
+  group: codeql-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  analyze:
+    name: Analyze (${{ matrix.language }})
+    runs-on: ubuntu-latest
+    permissions:
+      security-events: write
+      packages: read
+      contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          # build-mode: none uses CodeQL's buildless C# analysis, so the Aspire
+          # workload and a full restore/build aren't needed just to scan.
+          - language: csharp
+            build-mode: none
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v3
+        with:
+          languages: ${{ matrix.language }}
+          build-mode: ${{ matrix.build-mode }}
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v3
+        with:
+          category: "/language:${{ matrix.language }}"

.github/workflows/dependabot-approve-and-automerge.yml

@@ -15,12 +15,17 @@ jobs:
         uses: dependabot/fetch-metadata@v3.1.0
         with:
           github-token: "${{ secrets.GITHUB_TOKEN }}"
+      # Only auto-approve/merge patch and minor updates. A major bump can carry
+      # breaking changes that still compile and pass tests, then ship to consumers
+      # unnoticed -- leave majors for a human to review and merge.
       - name: Approve a PR
+        if: steps.metadata.outputs.update-type == 'version-update:semver-patch' || steps.metadata.outputs.update-type == 'version-update:semver-minor'
         run: gh pr review --approve "$PR_URL"
         env:
           PR_URL: ${{github.event.pull_request.html_url}}
           GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
       - name: Enable auto-merge for Dependabot PRs
+        if: steps.metadata.outputs.update-type == 'version-update:semver-patch' || steps.metadata.outputs.update-type == 'version-update:semver-minor'
         run: gh pr merge --auto --merge "$PR_URL"
         env:
           PR_URL: ${{github.event.pull_request.html_url}}

.github/workflows/release.yml

@@ -7,12 +7,18 @@ env:
   DOTNET_SKIP_FIRST_TIME_EXPERIENCE: 1
   DOTNET_NOLOGO: true
 
+# Serialize releases so two manual dispatches can't publish the same version twice.
+concurrency:
+  group: release
+  cancel-in-progress: false
+
 jobs:
   release:
     runs-on: ubuntu-latest
     permissions:
       contents: write
       packages: write
+      id-token: write   # required for NuGet.org trusted publishing (OIDC)
     outputs:
       version: ${{ steps.version.outputs.version }}
     steps:
@@ -75,13 +81,23 @@ jobs:
             --source https://nuget.pkg.github.com/${{ github.repository_owner }}/index.json \
             --skip-duplicate
 
-      # Uncomment when ready to publish to NuGet.org (requires NUGET_API_KEY secret)
-      # - name: Publish to NuGet.org
-      #   run: >
-      #     dotnet nuget push "./artifacts/*.nupkg"
-      #     -k ${{ secrets.NUGET_API_KEY }}
-      #     -s https://api.nuget.org/v3/index.json
-      #     --skip-duplicate
+      # Publish to NuGet.org via Trusted Publishing (OIDC) -- no long-lived API
+      # key is stored in GitHub. One-time setup on NuGet.org: create a trusted
+      # publisher policy for this repo + the Release workflow, then set the
+      # NUGET_USER secret to the owning NuGet.org account/organization name.
+      # https://learn.microsoft.com/nuget/nuget-org/trusted-publishing
+      - name: NuGet login (trusted publishing)
+        id: nuget-login
+        uses: NuGet/login@v1
+        with:
+          user: ${{ secrets.NUGET_USER }}
+
+      - name: Publish to NuGet.org
+        run: >
+          dotnet nuget push "./artifacts/*.nupkg"
+          --api-key ${{ steps.nuget-login.outputs.NUGET_API_KEY }}
+          --source https://api.nuget.org/v3/index.json
+          --skip-duplicate
 
   # Publish the released version as the default (stable) documentation. Reuses
   # docs.yml so the gh-pages layout and version manifest stay in one place.

.github/workflows/version-bump.yml

@@ -11,6 +11,7 @@ on:
         options:
           - major
           - minor
+          - patch
 
 jobs:
   bump:

README.md

@@ -28,19 +28,56 @@ infrastructure — so you can adopt only what you need.
 
 ## Packages
 
+Adopt only what you need — every package is independently versioned and focused on a single concern.
+
+**Core**
+
+| Package | Description |
+|---|---|
+| **Vulthil.Results** | Result primitives for explicit success/failure flows without exceptions. |
+| **Vulthil.SharedKernel** | Domain primitives — aggregate roots, entities, domain events, and domain exceptions. |
+
+**Application & API**
+
+| Package | Description |
+|---|---|
+| **Vulthil.SharedKernel.Application** | CQRS handlers, pipeline behaviors, and FluentValidation integration. |
+| **Vulthil.SharedKernel.Api** | Minimal-API endpoint helpers and `Result`-to-HTTP conversion. |
+
+**Persistence & Outbox**
+
+| Package | Description |
+|---|---|
+| **Vulthil.SharedKernel.Outbox** | Transactional domain-event outbox engine; persistence-agnostic. |
+| **Vulthil.SharedKernel.Outbox.EntityFrameworkCore** | EF Core implementation of the domain-event outbox. |
+| **Vulthil.SharedKernel.Infrastructure** | EF Core persistence, transactions, and outbox wiring. |
+| **Vulthil.SharedKernel.Infrastructure.Relational** | Shared relational helpers for the provider packages. |
+| **Vulthil.SharedKernel.Infrastructure.Npgsql** | PostgreSQL/Npgsql EF Core mappings and optimizations. |
+| **Vulthil.SharedKernel.Infrastructure.MySql** | MySQL EF Core mappings and optimizations. |
+| **Vulthil.SharedKernel.Infrastructure.Cosmos** | Azure Cosmos DB EF Core mappings and optimizations. |
+
+**Messaging**
+
+| Package | Description |
+|---|---|
+| **Vulthil.Messaging.Abstractions** | Contracts for producers, consumers, and request/reply boundaries. |
+| **Vulthil.Messaging** | Composition APIs for consumers, queues, and hosted processing. |
+| **Vulthil.Messaging.RabbitMq** | RabbitMQ transport for the messaging abstractions. |
+| **Vulthil.Messaging.Outbox** | Transactional bus-publish outbox that eliminates the dual-write problem. |
+| **Vulthil.Messaging.Inbox** | Idempotent-receiver (inbox) consume filter for exactly-once processing. |
+| **Vulthil.Messaging.Inbox.EntityFrameworkCore** | Shared EF Core primitives for the inbox idempotency store. |
+| **Vulthil.Messaging.Inbox.Relational** | Relational EF Core idempotency store (transactional exactly-once). |
+| **Vulthil.Messaging.Inbox.Cosmos** | Azure Cosmos DB idempotency store (effectively-once). |
+| **Vulthil.Messaging.TestHarness** | In-memory harness for asserting messaging flows in tests. |
+
+**Hosting & Testing**
+
 | Package | Description |
 |---|---|
-| **Vulthil.Results** | Small result primitives for explicit success/failure flows without exceptions. |
-| **Vulthil.SharedKernel** | Core domain primitives and base abstractions for shared domain logic. |
-| **Vulthil.SharedKernel.Application** | Application-layer building blocks such as handlers, pipelines, and validation helpers. |
-| **Vulthil.SharedKernel.Infrastructure** | Infrastructure helpers for persistence, transactions, outbox, and EF Core integration. |
-| **Vulthil.SharedKernel.Api** | API-layer helpers for endpoints, controllers, and cross-cutting HTTP concerns. |
-| **Vulthil.Messaging.Abstractions** | Messaging contracts for producers/consumers and request/reply boundaries. |
-| **Vulthil.Messaging** | Messaging composition APIs for configuring consumers, queues, and hosted processing. |
-| **Vulthil.Messaging.RabbitMq** | RabbitMQ implementation for the Vulthil messaging abstractions. |
-| **Vulthil.Messaging.TestHarness** | Test utilities for validating messaging flows in integration and component tests. |
-| **Vulthil.Extensions.Testing** | Testing-oriented extensions for asserting and composing application behaviors. |
-| **Vulthil.xUnit** | Reusable xUnit base infrastructure for integration and unit test composition. |
+| **Vulthil.Extensions.Hosting** | Hosting abstractions, including `IRestartableHostedService`. |
+| **Vulthil.Extensions.Testing** | Testing helpers such as polling utilities for eventual consistency. |
+| **Vulthil.xUnit** | xUnit base classes with Testcontainers, Respawn, and AutoMocker. |
+| **Vulthil.xUnit.Cosmos** | Cosmos DB emulator fixture for xUnit integration tests. |
 
 ## Documentation
 

eng/bump_version.py

@@ -1,36 +1,52 @@
 #!/usr/bin/env python3
-"""Bumps the Major.Minor base version in version.json without committing.
+"""Bumps the pinned Major.Minor.Patch version in version.json without committing.
 
-Only the "version" field is touched; every other nbgv setting (such as
-versionHeightOffset and the release config) is preserved verbatim. The new
-version is written to the GITHUB_OUTPUT "version" key for the calling workflow.
+Only the "version" field is touched; every other nbgv setting (the release
+config and cloud-build options) is preserved verbatim. The version is written as
+a full three-segment value so the released NuGet package version is exactly that
+value -- nbgv puts the git height in the unused fourth integer, which never
+appears in the package version. The new version is also written to the
+GITHUB_OUTPUT "version" key for the calling workflow.
+
+Bump types:
+    major   1.4.2 -> 2.0.0
+    minor   1.4.2 -> 1.5.0
+    patch   1.4.2 -> 1.4.3
 """
 import json
 import os
 import sys
 
 VERSION_FILE = "version.json"
+VALID_BUMPS = ("major", "minor", "patch")
 
 
-def main():
-    bump_type = sys.argv[1] if len(sys.argv) > 1 else "minor"
-
-    with open(VERSION_FILE, encoding="utf-8") as handle:
-        data = json.load(handle)
-
-    raw = str(data.get("version", "0.0"))
+def next_version(raw, bump_type):
     core = raw.split("-", 1)[0]
     parts = core.split(".")
     major = int(parts[0]) if len(parts) > 0 and parts[0] else 0
     minor = int(parts[1]) if len(parts) > 1 and parts[1] else 0
+    patch = int(parts[2]) if len(parts) > 2 and parts[2] else 0
 
     if bump_type == "major":
-        major += 1
-        minor = 0
-    else:
-        minor += 1
+        return f"{major + 1}.0.0"
+    if bump_type == "minor":
+        return f"{major}.{minor + 1}.0"
+    return f"{major}.{minor}.{patch + 1}"
+
+
+def main():
+    bump_type = sys.argv[1] if len(sys.argv) > 1 else "minor"
+    if bump_type not in VALID_BUMPS:
+        sys.exit(
+            f"Unknown bump type '{bump_type}'; expected one of {', '.join(VALID_BUMPS)}."
+        )
+
+    with open(VERSION_FILE, encoding="utf-8") as handle:
+        data = json.load(handle)
 
-    new_version = f"{major}.{minor}"
+    raw = str(data.get("version", "0.0.0"))
+    new_version = next_version(raw, bump_type)
     data["version"] = new_version
 
     with open(VERSION_FILE, "w", encoding="utf-8") as handle:

version.json

@@ -1,6 +1,5 @@
 {
-  "version": "0.0",
-  "versionHeightOffset": 7,
+  "version": "1.0.0",
   "release": {
     "firstUnstableTag": "preview"
   },