Spike: Skill-driven aspire init with unified agent skill

.agents/skills/aspire-init/references/docker-compose.md

@@ -0,0 +1,214 @@
+# Docker Compose migration
+
+Use this reference when the repo has a `docker-compose.yml` or `compose.yml` file. Docker Compose files are one of the most valuable discovery sources — they document the infrastructure the app actually needs to run locally.
+
+## When to load this reference
+
+- A `docker-compose.yml`, `compose.yml`, or `docker-compose.override.yml` exists anywhere in the repo
+- The repo has setup scripts that call `docker compose up` as part of the dev workflow
+
+## Profiles
+
+Docker Compose files can use `profiles:` to organize services into named groups. Not all services run at once — the developer chooses which profiles to activate.
+
+Example from a real repo:
+
+```yaml
+services:
+  mssql:
+    image: mcr.microsoft.com/mssql/server:2022-latest
+    profiles: [cloud, mssql]
+  postgres:
+    image: postgres:14
+    profiles: [postgres, ef]
+  redis:
+    image: redis:alpine
+    profiles: [redis, cloud]
+  storage:
+    image: mcr.microsoft.com/azure-storage/azurite:latest
+    profiles: [storage, cloud]
+  mail:
+    image: sj26/mailcatcher:latest
+    profiles: [mail]
+```
+
+When profiles are present:
+
+1. **List them clearly** — show the user which profiles exist and what services each activates
+2. **Ask which to target** — *"Your docker-compose has profiles: cloud, mssql, postgres, storage, redis, mail. Which ones represent your typical local dev stack?"*
+3. **Model only selected profiles** — services in unselected profiles are skipped entirely
+4. **Services without profiles always run** — if a service has no `profiles:` key, include it regardless of profile selection
+5. **Profile-specific infrastructure implies choices** — `mssql` vs `postgres` profiles often mean the repo supports multiple database backends. Ask which one to model in the AppHost.
+
+## Image-to-integration mapping
+
+Prefer typed Aspire integrations over raw `AddContainer()`. Use `aspire docs search <technology>` to check for available integrations.
+
+Common mappings:
+
+| Compose image | Aspire integration | Method |
+|---------------|-------------------|--------|
+| `postgres:*` | `Aspire.Hosting.PostgreSQL` | `AddPostgres()` |
+| `mcr.microsoft.com/mssql/server:*` | `Aspire.Hosting.SqlServer` | `AddSqlServer()` |
+| `mysql:*` / `mariadb:*` | `Aspire.Hosting.MySql` | `AddMySql()` |
+| `redis:*` | `Aspire.Hosting.Redis` | `AddRedis()` |
+| `rabbitmq:*` | `Aspire.Hosting.RabbitMQ` | `AddRabbitMQ()` |
+| `mongo:*` | `Aspire.Hosting.MongoDB` | `AddMongoDB()` |
+| `mcr.microsoft.com/azure-storage/azurite:*` | `Aspire.Hosting.Azure.Storage` | `AddAzureStorage().RunAsEmulator()` |
+| `kafka`, `confluentinc/cp-kafka:*` | `Aspire.Hosting.Kafka` | `AddKafka()` |
+| `nats:*` | `Aspire.Hosting.Nats` | `AddNats()` |
+| `mcr.microsoft.com/azure-messaging/servicebus-emulator:*` | `Aspire.Hosting.Azure.ServiceBus` | `AddAzureServiceBus().RunAsEmulator()` |
+
+For images not in this list, use `aspire docs search` to check, then fall back to `AddContainer()`.
+
+## Environment variable interpolation
+
+Compose files use `${VAR}` syntax to reference variables from `.env` files:
+
+```yaml
+environment:
+  MSSQL_SA_PASSWORD: ${MSSQL_PASSWORD}
+  POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
+```
+
+**⚠️ CRITICAL: Do not model passwords for typed Aspire integrations.**
+
+`AddPostgres()`, `AddSqlServer()`, `AddRedis()`, `AddMySql()`, `AddRabbitMQ()`, and other typed integrations **auto-generate secure passwords**. The compose file needed `POSTGRES_PASSWORD` because Compose doesn't manage credentials — Aspire does. If you see a compose password variable that maps to a typed integration, **skip it entirely**. Do not create an `AddParameter` for it.
+
+```csharp
+// ❌ WRONG — don't model passwords that Aspire auto-generates
+var pgPassword = builder.AddParameter("postgres-password", secret: true);
+var postgres = builder.AddPostgres("postgres", password: pgPassword);
+
+// ✅ RIGHT — let Aspire handle the password
+var postgres = builder.AddPostgres("postgres");
+```
+
+Use `aspire docs get <integration-slug>` to check what each typed integration manages automatically. Look for the "Connection properties" section — if it lists `Password`, the integration handles it.
+
+When you see a `${VAR}` pattern in compose:
+
+1. **Check if it maps to a typed integration** — if `POSTGRES_PASSWORD`, `MSSQL_SA_PASSWORD`, `MYSQL_ROOT_PASSWORD`, `RABBITMQ_DEFAULT_PASS`, etc. are used by a typed Aspire integration, **skip them** — Aspire manages these
+2. **Trace non-integration variables** — find them in the `.env` or `.env.example` file
+3. **Classify** — is it a secret (API key, token) or plain config?
+4. **Model it** — secrets become `AddParameter(name, secret: true)`, plain config becomes `AddParameter(name)` with a default or `WithEnvironment()` directly
+
+## Volume mapping
+
+| Compose volume type | Aspire equivalent | Notes |
+|--------------------|--------------------|-------|
+| Named volume (`mssql_data:/var/opt/mssql`) | `WithDataVolume()` | Preferred — Aspire manages lifecycle |
+| Named volume (custom name) | `WithDataVolume(name: "custom")` | Preserves the name for familiarity |
+| Bind mount (`./data:/app/data`) | `WithBindMount("./data", "/app/data")` | Use for config files, scripts, or shared data |
+| Bind mount for config (`./config.json:/etc/config.json`) | `WithBindMount(...)` | Preserve for config injection |
+
+**Tip:** If the compose file mounts migration scripts or SQL files into a database container, those are likely init scripts. See "Init and setup scripts" below.
+
+## Dependency ordering
+
+Compose `depends_on` maps to Aspire's `WaitFor()`:
+
+```yaml
+# Compose
+services:
+  api:
+    depends_on:
+      - mssql
+      - redis
+```
+
+```csharp
+// Aspire
+var api = builder.AddProject<Projects.Api>("api")
+    .WithReference(mssql)
+    .WithReference(redis)
+    .WaitFor(mssql)
+    .WaitFor(redis);
+```
+
+`WithReference()` establishes the connection. `WaitFor()` ensures the dependency is healthy before the consuming service starts. Use both together.
+
+For `depends_on` with `condition: service_healthy`, the `WaitFor()` mapping is especially important — it replicates the same behavior.
+
+## Build contexts
+
+Compose services with `build:` are built from source, not pulled as images:
+
+```yaml
+services:
+  worker:
+    build:
+      context: ./worker
+      dockerfile: Dockerfile
+```
+
+Map these to `AddDockerfile()`:
+
+```csharp
+var worker = builder.AddDockerfile("worker", "../worker")
+    .WithHttpEndpoint(targetPort: 8080);
+```
+
+However, **prefer native Aspire project hosting over Dockerfiles when possible**. If the build context contains a `.csproj`, use `AddProject<T>()`. If it's a Node.js app, use `AddNodeApp()` or `AddViteApp()`. Dockerfiles are a last resort for Aspire modeling — they lose service discovery, health checks, and hot reload.
+
+## Init and setup scripts
+
+Repos often have setup scripts alongside their compose files:
+
+- `setup_azurite.ps1` — initializes storage emulator containers and queues
+- `migrate.ps1` / `ef_migrate.ps1` — runs database migrations
+- `setup_secrets.ps1` — configures .NET user secrets
+- `create_certificates_*.sh` — generates dev certificates
+
+**Present the user with options for how to handle these:**
+
+1. **Model as a lifecycle command on the relevant resource** — for example, a database migration script can be a startup command on the database resource. This runs automatically when the resource starts.
+   → *"Your repo has a migrate.ps1 that runs SQL migrations against the database. I can model this as a startup lifecycle hook on the database resource so migrations run automatically when you `aspire start`. Want that?"*
+
+2. **Model as a standalone executable resource** — for scripts that don't map cleanly to a single resource, use `AddExecutable()` with `WaitForCompletion()` so dependent services wait for the script to finish.
+
+3. **Leave as manual** — some setup scripts are one-time-only (like certificate generation) and don't need to run every time. Note them in the AppHost as a comment and move on.
+
+The right choice depends on the script. Present the tradeoff and let the user decide.
+
+## Putting it together
+
+A compose file like:
+
+```yaml
+services:
+  mssql:
+    image: mcr.microsoft.com/mssql/server:2022-latest
+    environment:
+      MSSQL_SA_PASSWORD: ${MSSQL_PASSWORD}
+    volumes:
+      - mssql_data:/var/opt/mssql
+    ports:
+      - "1433:1433"
+  redis:
+    image: redis:alpine
+    volumes:
+      - redis_data:/data
+    ports:
+      - "6379:6379"
+```
+
+Becomes:
+
+```csharp
+// ✅ Let Aspire auto-generate the SA password — don't model MSSQL_PASSWORD
+var mssql = builder.AddSqlServer("mssql")
+    .WithDataVolume();
+
+var redis = builder.AddRedis("redis")
+    .WithDataVolume();
+```
+
+Note: for typed integrations like `AddSqlServer()` and `AddRedis()`, you don't need to map ports or passwords — Aspire handles both. You also don't need to model `redis_data` as a named volume — `WithDataVolume()` handles persistence. The `${MSSQL_PASSWORD}` from the compose file is skipped entirely because `AddSqlServer()` auto-generates a secure SA password.
+
+## Common pitfalls
+
+- **Don't model every compose service** — some are dev-only tools (mailcatcher, reverse proxies, SAML IdPs for testing). Ask the user which are essential vs nice-to-have.
+- **Don't preserve hardcoded ports from compose** — Aspire manages ports dynamically. Only preserve a port if the user confirms it's required for external reasons (OAuth callbacks, etc.).
+- **Don't duplicate compose's `.env` interpolation** — Aspire parameters replace this pattern. Trace each `${VAR}` to its source and model it properly.
+- **Watch for services that conflict on the same port** — compose profiles often have services sharing ports (e.g., `mssql` and `postgres` both on different profiles). If the user selects conflicting profiles, surface the conflict.