@opengroundplan/core 0.1.1

package/templates/architectures/vertical-slice/files/tests/test_architecture.py

@@ -0,0 +1,32 @@
+"""The one rule of this architecture, enforced instead of documented.
+
+Runs the same contracts as `lint-imports`, so CI fails whether it invokes the linter
+directly or just runs the test suite.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from pathlib import Path
+
+import pytest
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+
+
+def test_import_contracts_hold() -> None:
+    linter = shutil.which("lint-imports")
+    if linter is None:
+        # Skipping would mean the boundary is unenforced and nobody notices.
+        pytest.fail("import-linter is not installed. Run: uv add --dev import-linter")
+
+    # Fixed argv, no shell.
+    result = subprocess.run(
+        [linter],
+        cwd=REPO_ROOT,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    assert result.returncode == 0, result.stdout + result.stderr

package/templates/bases/dotnet-aspire/blueprint.yaml

@@ -0,0 +1,120 @@
+id: dotnet-aspire
+kind: base
+name: .NET Aspire
+description: >-
+  .NET Aspire distributed application host with a shared ServiceDefaults project
+  (OpenTelemetry, service discovery, standard resilience, health checks) and one
+  minimal ASP.NET Core service wired into the orchestrator.
+stack: dotnet
+tags:
+  - dotnet
+  - aspire
+  - aspnetcore
+  - distributed
+  - opentelemetry
+  - service-discovery
+
+sources:
+  - name: Aspire
+    url: https://github.com/microsoft/aspire
+    license: MIT
+    adapted: >-
+      ServiceDefaults/Extensions.cs — the AddServiceDefaults, ConfigureOpenTelemetry,
+      AddOpenTelemetryExporters, AddDefaultHealthChecks and MapDefaultEndpoints extension
+      methods follow the aspire-servicedefaults template.
+
+# ServiceDefaults already builds a TracerProvider, a MeterProvider and an OTLP exporter
+# for every hosted service. Declared on both sides because assertNoConflicts only reports
+# a pair from whichever id sorts first.
+conflicts:
+  - observability-otel
+
+provides:
+  - service-host
+  - http-api
+  - health-checks
+  - opentelemetry
+  - service-discovery
+
+# Aspire orchestrates .NET application/system architectures. Frontend layouts (FSD,
+# Next.js colocation) and the AI-workflow styles are not what this base materializes.
+supportsArchitectures:
+  - layered
+  - clean
+  - hexagonal
+  - onion
+  - vertical-slice
+  - monolith
+  - modular-monolith
+  - cqrs
+  - microservices
+  - mvc-mvvm
+  - event-driven
+  - ddd-tactical
+
+variables:
+  - name: dotnetTargetFramework
+    prompt: Target framework for every project
+    type: select
+    default: net10.0
+    choices:
+      - value: net10.0
+        label: .NET 10 (LTS)
+  - name: dotnetSdkVersion
+    prompt: Minimum .NET SDK pinned in global.json
+    type: string
+    default: '10.0.100'
+  - name: aspireVersion
+    prompt: Aspire AppHost SDK version
+    type: string
+    default: 13.4.6
+  - name: extensionsVersion
+    prompt: Microsoft.Extensions.* package version (resilience, service discovery)
+    type: string
+    default: 10.8.0
+  - name: openTelemetryVersion
+    prompt: OpenTelemetry package version
+    type: string
+    default: 1.17.0
+  - name: serviceName
+    prompt: Aspire resource name for the example service
+    type: string
+    default: api
+
+  # Names match the dotnet-webapi base so a dotnet interview asks these once. Defaults differ
+  # from that base's 5080/7080 so both can run side by side.
+  - name: httpPort
+    prompt: Local HTTP port for the example service during development
+    type: number
+    default: 5100
+    required: false
+
+  - name: httpsPort
+    prompt: Local HTTPS port for the example service during development
+    type: number
+    default: 7100
+    required: false
+
+files:
+  - from: files/**/*
+    to: .
+
+  # Central package management: versions live in Directory.Packages.props and projects
+  # reference without one. A bare Version= on a PackageReference fails restore (NU1008).
+  - from: files/Directory.Packages.props
+    to: .
+    onConflict: merge
+    when: "stack == 'dotnet'"
+
+  # The solution is completed declaratively rather than by `dotnet sln add`, which runs
+  # after the first build and is skippable — a solution missing projects that exist on
+  # disk builds green while covering less than the repo contains (ADR 0005, spec 003).
+  - from: files/__solutionName.dot__.slnx
+    to: .
+    onConflict: merge
+    when: "stack == 'dotnet'"
+
+postApply:
+  # Restore only — no build, no network beyond NuGet, and safe to skip when the SDK is absent.
+  - run: dotnet restore
+    optional: true

package/templates/bases/dotnet-aspire/files/Directory.Build.props

@@ -0,0 +1,11 @@
+<Project>
+
+  <!-- Framework and language settings live here so no individual csproj restates them. -->
+  <PropertyGroup>
+    <TargetFramework>{{ dotnetTargetFramework }}</TargetFramework>
+    <LangVersion>latest</LangVersion>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+</Project>

package/templates/bases/dotnet-aspire/files/Directory.Packages.props

@@ -0,0 +1,17 @@
+<Project>
+
+  <PropertyGroup>
+    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
+    <CentralPackageTransitivePinningEnabled>true</CentralPackageTransitivePinningEnabled>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageVersion Include="Microsoft.Extensions.Http.Resilience" Version="{{ extensionsVersion }}" />
+    <PackageVersion Include="Microsoft.Extensions.ServiceDiscovery" Version="{{ extensionsVersion }}" />
+    <PackageVersion Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" Version="{{ openTelemetryVersion }}" />
+    <PackageVersion Include="OpenTelemetry.Extensions.Hosting" Version="{{ openTelemetryVersion }}" />
+    <PackageVersion Include="OpenTelemetry.Instrumentation.AspNetCore" Version="{{ openTelemetryVersion }}" />
+    <PackageVersion Include="OpenTelemetry.Instrumentation.Http" Version="{{ openTelemetryVersion }}" />
+    <PackageVersion Include="OpenTelemetry.Instrumentation.Runtime" Version="{{ openTelemetryVersion }}" />
+  </ItemGroup>
+</Project>

package/templates/bases/dotnet-aspire/files/README.md

@@ -0,0 +1,60 @@
+# {{ solutionName | title }}
+
+A .NET Aspire distributed application. The AppHost orchestrates every resource; each service
+picks up OpenTelemetry, service discovery, resilient HTTP, and health checks from the shared
+`ServiceDefaults` project.
+
+## Requirements
+
+- .NET SDK {{ dotnetSdkVersion }} or later (pinned in `global.json`)
+- A container runtime (Docker Desktop or Podman) for Aspire-managed resources
+
+## Run
+
+```bash
+dotnet restore
+dotnet run --project src/{{ solutionName | pascal }}.AppHost
+```
+
+The Aspire dashboard prints its URL on startup. From there you can reach the `{{ serviceName | kebab }}`
+resource, its logs, traces, and metrics.
+
+Example endpoint:
+
+```bash
+curl "http://localhost:{{ httpPort }}/api/items?take=5"
+```
+
+## Layout
+
+```
+{{ solutionName | pascal }}.slnx
+aspire.config.json                              points the Aspire CLI at the AppHost
+Directory.Build.props                           shared target framework and language settings
+src/
+  {{ solutionName | pascal }}.AppHost/           orchestration: what runs and how it connects
+  {{ solutionName | pascal }}.ServiceDefaults/   telemetry, discovery, resilience, health checks
+  {{ solutionName | pascal }}.Api/               example HTTP service
+```
+
+## Configuration
+
+Settings live in `appsettings.json`. `ApiOptions` (`src/{{ solutionName | pascal }}.Api/Configuration/`)
+declares the shape and bounds, and is validated at startup — a bad value fails the boot rather
+than the first request.
+
+| Setting | Environment variable | Meaning |
+| --- | --- | --- |
+| `Api:DisplayName` | `Api__DisplayName` | Public-facing service name |
+| `Api:DefaultPageSize` | `Api__DefaultPageSize` | Page size when the caller omits `take` |
+| `Api:MaxPageSize` | `Api__MaxPageSize` | Upper bound applied to `take` |
+
+Never commit secrets. Use `dotnet user-secrets` locally and the platform's secret store elsewhere.
+
+## Adding a service
+
+1. Create the project under `src/` and add it to `{{ solutionName | pascal }}.slnx`.
+2. Reference `{{ solutionName | pascal }}.ServiceDefaults` and call `builder.AddServiceDefaults()`
+   plus `app.MapDefaultEndpoints()`.
+3. Add a `ProjectReference` in the AppHost csproj, then register it in `AppHost.cs` with
+   `builder.AddProject<...>("name")`.

package/templates/bases/dotnet-aspire/files/__solutionName.dot__.slnx

@@ -0,0 +1,7 @@
+<Solution>
+  <Folder Name="/src/">
+    <Project Path="src/{{ solutionName | pascal }}.AppHost/{{ solutionName | pascal }}.AppHost.csproj" />
+    <Project Path="src/{{ solutionName | pascal }}.ServiceDefaults/{{ solutionName | pascal }}.ServiceDefaults.csproj" />
+    <Project Path="src/{{ solutionName | pascal }}.Api/{{ solutionName | pascal }}.Api.csproj" />
+  </Folder>
+</Solution>

package/templates/bases/dotnet-aspire/files/aspire.config.json

@@ -0,0 +1,5 @@
+{
+  "appHost": {
+    "path": "src/{{ solutionName | pascal }}.AppHost/{{ solutionName | pascal }}.AppHost.csproj"
+  }
+}

package/templates/bases/dotnet-aspire/files/gitignore

@@ -0,0 +1,44 @@
+# Build output
+[Bb]in/
+[Oo]bj/
+[Oo]ut/
+[Dd]ebug/
+[Rr]elease/
+artifacts/
+
+# NuGet
+*.nupkg
+*.snupkg
+packages/
+.nuget/
+
+# Aspire CLI local state
+.aspire/
+
+# User-specific / IDE
+*.user
+*.suo
+*.userosscache
+*.sln.docstates
+.vs/
+.vscode/
+.idea/
+*.DotSettings.user
+
+# Local secrets and environment overrides
+appsettings.Local.json
+*.local.json
+.env
+.env.*
+!.env.example
+
+# Tooling output
+TestResults/
+coverage/
+*.coverage
+*.trx
+BenchmarkDotNet.Artifacts/
+
+# OS
+.DS_Store
+Thumbs.db

package/templates/bases/dotnet-aspire/files/global.json

@@ -0,0 +1,6 @@
+{
+  "sdk": {
+    "version": "{{ dotnetSdkVersion }}",
+    "rollForward": "latestMajor"
+  }
+}

package/templates/bases/dotnet-aspire/files/src/__solutionName.pascal__.Api/Configuration/ApiOptions.cs

@@ -0,0 +1,20 @@
+using System.ComponentModel.DataAnnotations;
+
+namespace {{ solutionName | pascal }}.Api.Configuration;
+
+/// Shape and bounds of the "Api" configuration section. Values come from appsettings.json
+/// and are overridable per environment via Api__DisplayName, Api__MaxPageSize, and so on.
+public sealed class ApiOptions
+{
+    public const string SectionName = "Api";
+
+    [Required]
+    [MinLength(1)]
+    public string DisplayName { get; set; } = string.Empty;
+
+    [Range(1, 1000)]
+    public int DefaultPageSize { get; set; }
+
+    [Range(1, 1000)]
+    public int MaxPageSize { get; set; }
+}

package/templates/bases/dotnet-aspire/files/src/__solutionName.pascal__.Api/Program.cs

@@ -0,0 +1,37 @@
+using Microsoft.Extensions.Options;
+using {{ solutionName | pascal }}.Api.Configuration;
+
+var builder = WebApplication.CreateBuilder(args);
+
+// OpenTelemetry, service discovery, resilient HTTP, health checks.
+builder.AddServiceDefaults();
+
+builder.Services.AddOptions<ApiOptions>()
+    .BindConfiguration(ApiOptions.SectionName)
+    .ValidateDataAnnotations()
+    // Fail at startup rather than on the first request that reads a bad setting.
+    .ValidateOnStart();
+
+builder.Services.AddProblemDetails();
+
+var app = builder.Build();
+
+app.UseExceptionHandler();
+app.UseStatusCodePages();
+
+// /health and /alive, from ServiceDefaults.
+app.MapDefaultEndpoints();
+
+app.MapGet("/api/items", (IOptions<ApiOptions> options, int? take) =>
+{
+    var settings = options.Value;
+    var size = Math.Clamp(take ?? settings.DefaultPageSize, 1, settings.MaxPageSize);
+
+    return Results.Ok(new
+    {
+        Service = settings.DisplayName,
+        Items = Enumerable.Range(1, size).Select(index => new { Id = index, Name = $"item-{index}" }),
+    });
+});
+
+app.Run();

package/templates/bases/dotnet-aspire/files/src/__solutionName.pascal__.Api/Properties/launchSettings.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://json.schemastore.org/launchsettings.json",
+  "profiles": {
+    "http": {
+      "commandName": "Project",
+      "dotnetRunMessages": true,
+      "launchBrowser": false,
+      "applicationUrl": "http://localhost:{{ httpPort }}",
+      "environmentVariables": {
+        "ASPNETCORE_ENVIRONMENT": "Development"
+      }
+    },
+    "https": {
+      "commandName": "Project",
+      "dotnetRunMessages": true,
+      "launchBrowser": false,
+      "applicationUrl": "https://localhost:{{ httpsPort }};http://localhost:{{ httpPort }}",
+      "environmentVariables": {
+        "ASPNETCORE_ENVIRONMENT": "Development"
+      }
+    }
+  }
+}

package/templates/bases/dotnet-aspire/files/src/__solutionName.pascal__.Api/__solutionName.pascal__.Api.csproj

@@ -0,0 +1,11 @@
+<Project Sdk="Microsoft.NET.Sdk.Web">
+
+  <PropertyGroup>
+    <InvariantGlobalization>true</InvariantGlobalization>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="../{{ solutionName | pascal }}.ServiceDefaults/{{ solutionName | pascal }}.ServiceDefaults.csproj" />
+  </ItemGroup>
+
+</Project>

package/templates/bases/dotnet-aspire/files/src/__solutionName.pascal__.Api/appsettings.Development.json

@@ -0,0 +1,8 @@
+{
+  "Logging": {
+    "LogLevel": {
+      "Default": "Debug",
+      "Microsoft.AspNetCore": "Information"
+    }
+  }
+}

package/templates/bases/dotnet-aspire/files/src/__solutionName.pascal__.Api/appsettings.json

@@ -0,0 +1,14 @@
+{
+  "Logging": {
+    "LogLevel": {
+      "Default": "Information",
+      "Microsoft.AspNetCore": "Warning"
+    }
+  },
+  "AllowedHosts": "*",
+  "Api": {
+    "DisplayName": "{{ solutionName | title }}",
+    "DefaultPageSize": 20,
+    "MaxPageSize": 100
+  }
+}

package/templates/bases/dotnet-aspire/files/src/__solutionName.pascal__.AppHost/AppHost.cs

@@ -0,0 +1,8 @@
+var builder = DistributedApplication.CreateBuilder(args);
+
+// The Projects.* class is generated by the Aspire SDK from the csproj ProjectReference.
+// kebab: Aspire rejects anything but letters, digits and hyphens at build time (ASPIRE006).
+builder.AddProject<Projects.{{ solutionName | pascal }}_Api>("{{ serviceName | kebab }}")
+    .WithHttpHealthCheck("/health");
+
+builder.Build().Run();

package/templates/bases/dotnet-aspire/files/src/__solutionName.pascal__.AppHost/Properties/launchSettings.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://json.schemastore.org/launchsettings.json",
+  "profiles": {
+    "https": {
+      "commandName": "Project",
+      "dotnetRunMessages": true,
+      "launchBrowser": true,
+      "applicationUrl": "https://localhost:17000;http://localhost:15000",
+      "environmentVariables": {
+        "ASPNETCORE_ENVIRONMENT": "Development",
+        "DOTNET_ENVIRONMENT": "Development",
+        "ASPIRE_DASHBOARD_OTLP_ENDPOINT_URL": "https://localhost:21000",
+        "ASPIRE_RESOURCE_SERVICE_ENDPOINT_URL": "https://localhost:22000"
+      }
+    },
+    "http": {
+      "commandName": "Project",
+      "dotnetRunMessages": true,
+      "launchBrowser": true,
+      "applicationUrl": "http://localhost:15000",
+      "environmentVariables": {
+        "ASPNETCORE_ENVIRONMENT": "Development",
+        "DOTNET_ENVIRONMENT": "Development",
+        "ASPIRE_DASHBOARD_OTLP_ENDPOINT_URL": "http://localhost:19000",
+        "ASPIRE_RESOURCE_SERVICE_ENDPOINT_URL": "http://localhost:20000"
+      }
+    }
+  }
+}

package/templates/bases/dotnet-aspire/files/src/__solutionName.pascal__.AppHost/__solutionName.pascal__.AppHost.csproj

@@ -0,0 +1,11 @@
+<Project Sdk="Aspire.AppHost.Sdk/{{ aspireVersion }}">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="../{{ solutionName | pascal }}.Api/{{ solutionName | pascal }}.Api.csproj" />
+  </ItemGroup>
+
+</Project>

package/templates/bases/dotnet-aspire/files/src/__solutionName.pascal__.AppHost/appsettings.Development.json

@@ -0,0 +1,8 @@
+{
+  "Logging": {
+    "LogLevel": {
+      "Default": "Information",
+      "Microsoft.AspNetCore": "Warning"
+    }
+  }
+}

package/templates/bases/dotnet-aspire/files/src/__solutionName.pascal__.AppHost/appsettings.json

@@ -0,0 +1,9 @@
+{
+  "Logging": {
+    "LogLevel": {
+      "Default": "Information",
+      "Microsoft.AspNetCore": "Warning",
+      "Aspire.Hosting.Dcp": "Warning"
+    }
+  }
+}

package/templates/bases/dotnet-aspire/files/src/__solutionName.pascal__.ServiceDefaults/Extensions.cs

@@ -0,0 +1,101 @@
+using Microsoft.AspNetCore.Builder;
+using Microsoft.AspNetCore.Diagnostics.HealthChecks;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Diagnostics.HealthChecks;
+using Microsoft.Extensions.Logging;
+using OpenTelemetry;
+using OpenTelemetry.Metrics;
+using OpenTelemetry.Trace;
+
+// Namespaced as Microsoft.Extensions.Hosting so every service picks these up via implicit usings.
+namespace Microsoft.Extensions.Hosting;
+
+/// Cross-cutting defaults every service in the solution shares.
+public static class Extensions
+{
+    private const string HealthEndpointPath = "/health";
+    private const string AlivenessEndpointPath = "/alive";
+
+    public static TBuilder AddServiceDefaults<TBuilder>(this TBuilder builder)
+        where TBuilder : IHostApplicationBuilder
+    {
+        builder.ConfigureOpenTelemetry();
+        builder.AddDefaultHealthChecks();
+
+        builder.Services.AddServiceDiscovery();
+        builder.Services.ConfigureHttpClientDefaults(http =>
+        {
+            http.AddStandardResilienceHandler();
+            http.AddServiceDiscovery();
+        });
+
+        return builder;
+    }
+
+    public static TBuilder ConfigureOpenTelemetry<TBuilder>(this TBuilder builder)
+        where TBuilder : IHostApplicationBuilder
+    {
+        builder.Logging.AddOpenTelemetry(logging =>
+        {
+            logging.IncludeFormattedMessage = true;
+            logging.IncludeScopes = true;
+        });
+
+        builder.Services.AddOpenTelemetry()
+            .WithMetrics(metrics => metrics
+                .AddAspNetCoreInstrumentation()
+                .AddHttpClientInstrumentation()
+                .AddRuntimeInstrumentation())
+            .WithTracing(tracing => tracing
+                .AddSource(builder.Environment.ApplicationName)
+                .AddAspNetCoreInstrumentation(options =>
+                    // Health probes fire constantly and would drown the useful traces.
+                    options.Filter = context =>
+                        !context.Request.Path.StartsWithSegments(HealthEndpointPath)
+                        && !context.Request.Path.StartsWithSegments(AlivenessEndpointPath))
+                .AddHttpClientInstrumentation());
+
+        builder.AddOpenTelemetryExporters();
+
+        return builder;
+    }
+
+    private static TBuilder AddOpenTelemetryExporters<TBuilder>(this TBuilder builder)
+        where TBuilder : IHostApplicationBuilder
+    {
+        // The AppHost injects this; without it there is no collector to export to.
+        var otlpEndpoint = builder.Configuration["OTEL_EXPORTER_OTLP_ENDPOINT"];
+
+        if (!string.IsNullOrWhiteSpace(otlpEndpoint))
+        {
+            builder.Services.AddOpenTelemetry().UseOtlpExporter();
+        }
+
+        return builder;
+    }
+
+    public static TBuilder AddDefaultHealthChecks<TBuilder>(this TBuilder builder)
+        where TBuilder : IHostApplicationBuilder
+    {
+        builder.Services.AddHealthChecks()
+            .AddCheck("self", () => HealthCheckResult.Healthy(), ["live"]);
+
+        return builder;
+    }
+
+    /// Maps /health (readiness) and /alive (liveness).
+    public static WebApplication MapDefaultEndpoints(this WebApplication app)
+    {
+        // Exposing probes publicly leaks topology; see https://aka.ms/aspire/healthchecks before widening.
+        if (app.Environment.IsDevelopment())
+        {
+            app.MapHealthChecks(HealthEndpointPath);
+            app.MapHealthChecks(AlivenessEndpointPath, new HealthCheckOptions
+            {
+                Predicate = registration => registration.Tags.Contains("live"),
+            });
+        }
+
+        return app;
+    }
+}

package/templates/bases/dotnet-aspire/files/src/__solutionName.pascal__.ServiceDefaults/__solutionName.pascal__.ServiceDefaults.csproj

@@ -0,0 +1,19 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <IsAspireSharedProject>true</IsAspireSharedProject>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <FrameworkReference Include="Microsoft.AspNetCore.App" />
+
+    <PackageReference Include="Microsoft.Extensions.Http.Resilience" />
+    <PackageReference Include="Microsoft.Extensions.ServiceDiscovery" />
+    <PackageReference Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" />
+    <PackageReference Include="OpenTelemetry.Extensions.Hosting" />
+    <PackageReference Include="OpenTelemetry.Instrumentation.AspNetCore" />
+    <PackageReference Include="OpenTelemetry.Instrumentation.Http" />
+    <PackageReference Include="OpenTelemetry.Instrumentation.Runtime" />
+  </ItemGroup>
+
+</Project>