devskill 2.0.6 → 2.0.8

package/skills/aspire/references/architecture.md

@@ -0,0 +1,341 @@
+# Architecture — Deep Dive
+
+This reference covers Aspire's internal architecture: the DCP engine, resource model, service discovery, networking, telemetry, and the eventing system.
+
+---
+
+## Developer Control Plane (DCP)
+
+The DCP is the **runtime engine** that Aspire uses in `aspire run` mode. Key facts:
+
+- Written in **Go** (not .NET)
+- Exposes a **Kubernetes-compatible API server** (local only, not a real K8s cluster)
+- Manages resource lifecycle: create, start, health-check, stop, restart
+- Runs containers via the local container runtime (Docker, Podman, Rancher)
+- Runs executables as native OS processes
+- Handles networking via a proxy layer with automatic port assignment
+- Provides the foundation for the Aspire Dashboard's real-time data
+
+### DCP vs Kubernetes
+
+| Aspect | DCP (local dev) | Kubernetes (production) |
+|---|---|---|
+| API | Kubernetes-compatible | Full Kubernetes API |
+| Scope | Single machine | Cluster |
+| Networking | Local proxy, auto ports | Service mesh, ingress |
+| Storage | Local volumes | PVCs, cloud storage |
+| Purpose | Developer inner loop | Production deployment |
+
+The Kubernetes-compatible API means Aspire understands the same resource abstractions, but DCP is **not** a Kubernetes distribution — it's a lightweight local runtime.
+
+---
+
+## Resource Model
+
+Everything in Aspire is a **resource**. The resource model is hierarchical:
+
+### Type hierarchy
+
+```
+IResource (interface)
+└── Resource (abstract base)
+    ├── ProjectResource          — .NET project reference
+    ├── ContainerResource        — Docker/OCI container
+    ├── ExecutableResource       — Native process (polyglot apps)
+    ├── ParameterResource        — Config value or secret
+    └── Infrastructure resources
+        ├── RedisResource
+        ├── PostgresServerResource
+        ├── MongoDBServerResource
+        ├── SqlServerResource
+        ├── RabbitMQServerResource
+        ├── KafkaServerResource
+        └── ... (one per integration)
+```
+
+### Resource properties
+
+Every resource has:
+- **Name** — unique identifier within the AppHost
+- **State** — lifecycle state (Starting, Running, FailedToStart, Stopping, Stopped, etc.)
+- **Annotations** — metadata attached to the resource
+- **Endpoints** — network endpoints exposed by the resource
+- **Environment variables** — injected into the process/container
+
+### Annotations
+
+Annotations are metadata bags attached to resources. Common built-in annotations:
+
+| Annotation | Purpose |
+|---|---|
+| `EndpointAnnotation` | Defines an HTTP/HTTPS/TCP endpoint |
+| `EnvironmentCallbackAnnotation` | Deferred env var resolution |
+| `HealthCheckAnnotation` | Health check configuration |
+| `ContainerImageAnnotation` | Docker image details |
+| `VolumeAnnotation` | Volume mount configuration |
+| `CommandLineArgsCallbackAnnotation` | Dynamic CLI arguments |
+| `ManifestPublishingCallbackAnnotation` | Custom publish behavior |
+
+### Resource lifecycle states
+
+```
+NotStarted → Starting → Running → Stopping → Stopped
+                 ↓                     ↓
+          FailedToStart           RuntimeUnhealthy
+                                       ↓
+                                  Restarting → Running
+```
+
+### DAG (Directed Acyclic Graph)
+
+Resources form a dependency graph. Aspire starts resources in topological order:
+
+```
+PostgreSQL ──→ API ──→ Frontend
+Redis ────────↗
+RabbitMQ ──→ Worker
+```
+
+1. PostgreSQL, Redis, and RabbitMQ start first (no dependencies)
+2. API starts after PostgreSQL and Redis are healthy
+3. Frontend starts after API is healthy
+4. Worker starts after RabbitMQ is healthy
+
+`.WaitFor()` adds a health-check gate to the dependency edge. Without it, the dependency starts but the downstream doesn't wait for health.
+
+---
+
+## Service Discovery
+
+Aspire injects environment variables into each resource so services can find each other. No service registry or DNS is needed — it's pure environment variable injection.
+
+### Connection strings
+
+For databases, caches, and message brokers:
+
+```
+ConnectionStrings__<resource-name>=<connection-string>
+```
+
+Examples:
+```
+ConnectionStrings__cache=localhost:6379
+ConnectionStrings__catalog=Host=localhost;Port=5432;Database=catalog;Username=postgres;Password=...
+ConnectionStrings__messaging=amqp://guest:guest@localhost:5672
+```
+
+### Service endpoints
+
+For HTTP/HTTPS services:
+
+```
+services__<resource-name>__<scheme>__0=<url>
+```
+
+Examples:
+```
+services__api__http__0=http://localhost:5234
+services__api__https__0=https://localhost:7234
+services__ml__http__0=http://localhost:8000
+```
+
+### How .WithReference() works
+
+```csharp
+var redis = builder.AddRedis("cache");
+var api = builder.AddProject<Projects.Api>("api")
+    .WithReference(redis);
+```
+
+This does:
+1. Adds `ConnectionStrings__cache=localhost:<auto-port>` to the API's environment
+2. Creates a dependency edge in the DAG (API depends on Redis)
+3. In the API service, `builder.Configuration.GetConnectionString("cache")` returns the connection string
+
+### Cross-language service discovery
+
+All languages use the same env var pattern:
+
+| Language | How to read |
+|---|---|
+| C# | `builder.Configuration.GetConnectionString("cache")` |
+| Python | `os.environ["ConnectionStrings__cache"]` |
+| JavaScript | `process.env.ConnectionStrings__cache` |
+| Go | `os.Getenv("ConnectionStrings__cache")` |
+| Java | `System.getenv("ConnectionStrings__cache")` |
+| Rust | `std::env::var("ConnectionStrings__cache")` |
+
+---
+
+## Networking
+
+### Proxy architecture
+
+In `aspire run` mode, DCP runs a reverse proxy for each exposed endpoint:
+
+```
+Browser → Proxy (auto-assigned port) → Actual Service (target port)
+```
+
+- **port** (the external port) — auto-assigned by DCP unless overridden
+- **targetPort** — the port your service actually listens on
+- All inter-service traffic goes through the proxy for observability
+
+```csharp
+// Let DCP auto-assign the external port, service listens on 8000
+builder.AddPythonApp("ml", "../ml", "main.py")
+    .WithHttpEndpoint(targetPort: 8000);
+
+// Fix the external port to 3000
+builder.AddViteApp("web", "../frontend")
+    .WithHttpEndpoint(port: 3000, targetPort: 5173);
+```
+
+### Endpoint types
+
+```csharp
+// HTTP endpoint
+.WithHttpEndpoint(port?, targetPort?, name?)
+
+// HTTPS endpoint
+.WithHttpsEndpoint(port?, targetPort?, name?)
+
+// Generic endpoint (TCP, custom schemes)
+.WithEndpoint(port?, targetPort?, scheme?, name?, isExternal?)
+
+// Mark endpoints as externally accessible (for deployment)
+.WithExternalHttpEndpoints()
+```
+
+---
+
+## Telemetry (OpenTelemetry)
+
+Aspire configures OpenTelemetry automatically for .NET services. For non-.NET services, you configure OpenTelemetry manually, pointing at the DCP collector.
+
+### What's auto-configured (.NET services)
+
+- **Distributed tracing** — HTTP client/server spans, database spans, messaging spans
+- **Metrics** — Runtime metrics, HTTP metrics, custom metrics
+- **Structured logging** — Logs correlated with trace context
+- **Exporter** — OTLP exporter pointing at the Aspire Dashboard
+
+### Configuring non-.NET services
+
+The DCP exposes an OTLP endpoint. Set these env vars in your non-.NET service:
+
+```
+OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
+OTEL_SERVICE_NAME=<your-service-name>
+```
+
+Aspire auto-injects `OTEL_EXPORTER_OTLP_ENDPOINT` via `.WithReference()` for the dashboard collector.
+
+### ServiceDefaults pattern
+
+The `ServiceDefaults` project is a shared configuration library that standardizes:
+- OpenTelemetry setup (tracing, metrics, logging)
+- Health check endpoints (`/health`, `/alive`)
+- Resilience policies (retries, circuit breakers via Polly)
+
+```csharp
+// In each .NET service's Program.cs
+builder.AddServiceDefaults();   // adds OTel, health checks, resilience
+// ... other service config ...
+app.MapDefaultEndpoints();      // maps /health and /alive
+```
+
+---
+
+## Health Checks
+
+### Built-in health checks
+
+Every integration adds health checks automatically on the client side:
+- Redis: `PING` command
+- PostgreSQL: `SELECT 1`
+- MongoDB: `ping` command
+- RabbitMQ: Connection check
+- etc.
+
+### WaitFor vs WithReference
+
+```csharp
+// WithReference: wires connection string + creates dependency edge
+// (downstream may start before dependency is healthy)
+.WithReference(db)
+
+// WaitFor: gates on health check — downstream won't start until healthy
+.WaitFor(db)
+
+// Typical pattern: both
+.WithReference(db).WaitFor(db)
+```
+
+### Custom health checks
+
+```csharp
+var api = builder.AddProject<Projects.Api>("api")
+    .WithHealthCheck("ready", "/health/ready")
+    .WithHealthCheck("live", "/health/live");
+```
+
+---
+
+## Eventing System
+
+The AppHost supports lifecycle events for reacting to resource state changes:
+
+```csharp
+builder.Eventing.Subscribe<ResourceReadyEvent>("api", (evt, ct) =>
+{
+    // Fires when "api" resource becomes healthy
+    Console.WriteLine($"API is ready at {evt.Resource.Name}");
+    return Task.CompletedTask;
+});
+
+builder.Eventing.Subscribe<BeforeResourceStartedEvent>("db", async (evt, ct) =>
+{
+    // Run database migrations before the DB resource is marked as started
+    await RunMigrations();
+});
+```
+
+### Available events
+
+| Event | When |
+|---|---|
+| `BeforeResourceStartedEvent` | Before a resource starts |
+| `ResourceReadyEvent` | Resource is healthy and ready |
+| `ResourceStateChangedEvent` | Any state transition |
+| `BeforeStartEvent` | Before the entire application starts |
+| `AfterEndpointsAllocatedEvent` | After all ports are assigned |
+
+---
+
+## Configuration
+
+### Parameters
+
+```csharp
+// Plain parameter
+var apiKey = builder.AddParameter("api-key");
+
+// Secret parameter (prompted at run, not logged)
+var dbPassword = builder.AddParameter("db-password", secret: true);
+
+// Use in resources
+var api = builder.AddProject<Projects.Api>("api")
+    .WithEnvironment("API_KEY", apiKey);
+
+var db = builder.AddPostgres("db", password: dbPassword);
+```
+
+### Configuration sources
+
+Parameters are resolved from (in priority order):
+1. Command-line arguments
+2. Environment variables
+3. User secrets (`dotnet user-secrets`)
+4. `appsettings.json` / `appsettings.{Environment}.json`
+5. Interactive prompt (for secrets during `aspire run`)

package/skills/aspire/references/cli-reference.md

@@ -0,0 +1,307 @@
+# CLI Reference — Complete Command Reference
+
+The Aspire CLI (`aspire`) is the primary interface for creating, running, and publishing distributed applications. It is cross-platform and installed standalone (not coupled to the .NET CLI, though `dotnet` commands also work).
+
+**Tested against:** Aspire CLI 13.1.0
+
+---
+
+## Installation
+
+```bash
+# Linux / macOS
+curl -sSL https://aspire.dev/install.sh | bash
+
+# Windows PowerShell
+irm https://aspire.dev/install.ps1 | iex
+
+# Verify
+aspire --version
+
+# Update the CLI itself
+aspire update --self
+```
+
+---
+
+## Global Options
+
+All commands support these options:
+
+| Option                | Description                                    |
+| --------------------- | ---------------------------------------------- |
+| `-d, --debug`         | Enable debug logging to the console            |
+| `--non-interactive`   | Disable all interactive prompts and spinners   |
+| `--wait-for-debugger` | Wait for a debugger to attach before executing |
+| `-?, -h, --help`      | Show help and usage information                |
+| `--version`           | Show version information                       |
+
+---
+
+## Command Reference
+
+### `aspire new`
+
+Create a new project from a template.
+
+```bash
+aspire new [<template>] [options]
+
+# Options:
+#   -n, --name <name>        Project name
+#   -o, --output <dir>       Output directory
+#   -s, --source <source>    NuGet source for templates
+#   -v, --version <version>  Version of templates to use
+#   --channel <channel>      Channel (stable, daily)
+
+# Examples:
+aspire new aspire-starter
+aspire new aspire-starter -n MyApp -o ./my-app
+aspire new aspire-ts-cs-starter
+aspire new aspire-py-starter
+aspire new aspire-apphost-singlefile
+```
+
+Available templates:
+
+- `aspire-starter` — ASP.NET Core/Blazor starter + AppHost + tests
+- `aspire-ts-cs-starter` — ASP.NET Core/React + AppHost
+- `aspire-py-starter` — FastAPI/React + AppHost
+- `aspire-apphost-singlefile` — Empty single-file AppHost
+
+### `aspire init`
+
+Initialize Aspire in an existing project or solution.
+
+```bash
+aspire init [options]
+
+# Options:
+#   -s, --source <source>    NuGet source for templates
+#   -v, --version <version>  Version of templates to use
+#   --channel <channel>      Channel (stable, daily)
+
+# Example:
+cd my-existing-solution
+aspire init
+```
+
+Adds AppHost and ServiceDefaults projects to an existing solution. Interactive prompts guide you through selecting which projects to orchestrate.
+
+### `aspire run`
+
+Start all resources locally using the DCP (Developer Control Plane).
+
+```bash
+aspire run [options] [-- <additional arguments>]
+
+# Options:
+#   --project <path>       Path to AppHost project file
+
+# Examples:
+aspire run
+aspire run --project ./src/MyApp.AppHost
+```
+
+Behavior:
+
+1. Builds the AppHost project
+2. Starts the DCP engine
+3. Creates resources in dependency order (DAG)
+4. Waits for health checks on gated resources
+5. Opens the dashboard in the default browser
+6. Streams logs to the terminal
+
+Press `Ctrl+C` to gracefully stop all resources.
+
+### `aspire add`
+
+Add a hosting integration to the AppHost.
+
+```bash
+aspire add [<integration>] [options]
+
+# Options:
+#   --project <path>         Target project file
+#   -v, --version <version>  Version of integration to add
+#   -s, --source <source>    NuGet source for integration
+
+# Examples:
+aspire add redis
+aspire add postgresql
+aspire add mongodb
+```
+
+### `aspire publish` (Preview)
+
+Generate deployment manifests from the AppHost resource model.
+
+```bash
+aspire publish [options] [-- <additional arguments>]
+
+# Options:
+#   --project <path>                   Path to AppHost project file
+#   -o, --output-path <path>           Output directory (default: ./aspire-output)
+#   --log-level <level>                Log level (trace, debug, information, warning, error, critical)
+#   -e, --environment <env>            Environment (default: Production)
+#   --include-exception-details        Include stack traces in pipeline logs
+
+# Examples:
+aspire publish
+aspire publish --output-path ./deploy
+aspire publish -e Staging
+```
+
+### `aspire config`
+
+Manage Aspire configuration settings.
+
+```bash
+aspire config <subcommand>
+
+# Subcommands:
+#   get <key>              Get a configuration value
+#   set <key> <value>      Set a configuration value
+#   list                   List all configuration values
+#   delete <key>           Delete a configuration value
+
+# Examples:
+aspire config list
+aspire config set telemetry.enabled false
+aspire config get telemetry.enabled
+aspire config delete telemetry.enabled
+```
+
+### `aspire cache`
+
+Manage disk cache for CLI operations.
+
+```bash
+aspire cache <subcommand>
+
+# Subcommands:
+#   clear                  Clear all cache entries
+
+# Example:
+aspire cache clear
+```
+
+### `aspire deploy` (Preview)
+
+Deploy the contents of an Aspire apphost to its defined deployment targets.
+
+```bash
+aspire deploy [options] [-- <additional arguments>]
+
+# Options:
+#   --project <path>                   Path to AppHost project file
+#   -o, --output-path <path>           Output path for deployment artifacts
+#   --log-level <level>                Log level (trace, debug, information, warning, error, critical)
+#   -e, --environment <env>            Environment (default: Production)
+#   --include-exception-details        Include stack traces in pipeline logs
+#   --clear-cache                      Clear deployment cache for current environment
+
+# Example:
+aspire deploy --project ./src/MyApp.AppHost
+```
+
+### `aspire do` (Preview)
+
+Execute a specific pipeline step and its dependencies.
+
+```bash
+aspire do <step> [options] [-- <additional arguments>]
+
+# Options:
+#   --project <path>                   Path to AppHost project file
+#   -o, --output-path <path>           Output path for artifacts
+#   --log-level <level>                Log level (trace, debug, information, warning, error, critical)
+#   -e, --environment <env>            Environment (default: Production)
+#   --include-exception-details        Include stack traces in pipeline logs
+
+# Example:
+aspire do build-images --project ./src/MyApp.AppHost
+```
+
+### `aspire update` (Preview)
+
+Update integrations in the Aspire project, or update the CLI itself.
+
+```bash
+aspire update [options]
+
+# Options:
+#   --project <path>       Path to AppHost project file
+#   --self                 Update the Aspire CLI itself to the latest version
+#   --channel <channel>    Channel to update to (stable, daily)
+
+# Examples:
+aspire update                          # Update project integrations
+aspire update --self                   # Update the CLI itself
+aspire update --self --channel daily   # Update CLI to daily build
+```
+
+### `aspire mcp`
+
+Manage the MCP (Model Context Protocol) server.
+
+```bash
+aspire mcp <subcommand>
+
+# Subcommands:
+#   init    Initialize MCP server configuration for detected agent environments
+#   start   Start the MCP server
+```
+
+#### `aspire mcp init`
+
+```bash
+aspire mcp init
+
+# Interactive — detects your AI environment and creates config files.
+# Supported environments:
+# - VS Code (GitHub Copilot)
+# - Copilot CLI
+# - Claude Code
+# - OpenCode
+```
+
+Generates the appropriate configuration file for your detected AI tool.
+See [MCP Server](mcp-server.md) for details.
+
+#### `aspire mcp start`
+
+```bash
+aspire mcp start
+
+# Starts the MCP server using STDIO transport.
+# This is typically invoked by your AI tool, not run manually.
+```
+
+---
+
+## Commands That Do NOT Exist
+
+The following commands are **not valid** in Aspire CLI 13.1. Use alternatives:
+
+| Invalid Command | Alternative                                                          |
+| --------------- | -------------------------------------------------------------------- |
+| `aspire build`  | Use `dotnet build ./AppHost`                                         |
+| `aspire test`   | Use `dotnet test ./Tests`                                            |
+| `aspire dev`    | Use `aspire run` (includes file watching)                            |
+| `aspire list`   | Use `aspire new --help` for templates, `aspire add` for integrations |
+
+---
+
+## .NET CLI equivalents
+
+The `dotnet` CLI can perform some Aspire tasks:
+
+| Aspire CLI                  | .NET CLI Equivalent              |
+| --------------------------- | -------------------------------- |
+| `aspire new aspire-starter` | `dotnet new aspire-starter`      |
+| `aspire run`                | `dotnet run --project ./AppHost` |
+| N/A                         | `dotnet build ./AppHost`         |
+| N/A                         | `dotnet test ./Tests`            |
+
+The Aspire CLI adds value with `publish`, `deploy`, `add`, `mcp`, `config`, `cache`, `do`, and `update` — commands that have no direct `dotnet` equivalent.