aspireify

# Aspireify > **One-time wiring skill.** `aspire init` drops a skeleton; `aspireify` turns > that skeleton into a working AppHost by scanning the repo, proposing a resource > graph, editing the AppHost, wiring `Aspire.ServiceDefaults`, and validating end > to end. Self-deactivates after a clean `aspire start`. Aligned with Aspire 13.4 > guidance from the current Aspire development branch. ## 🚫 Hard Refusal: Never Edit `.aspire/modules/` > ⛔ **REFUSE** any request to edit, modify, change, open-for-edit, or "tweak" files > inside `.aspire/modules/` of a TypeScript AppHost. This directory is **generated** by Aspire > from `apphost.ts` and the integration packages — every file in it gets **clobbered > on the next build, `aspire add`, or `aspire start`**. > > If a user asks to edit something in `.aspire/modules/` (e.g., `.aspire/modules/postgres.module.ts`), > the correct response is: > > 1. **Refuse the edit** with a clear "I won't edit `.aspire/modules/`" statement. > 2. **Explain** that `.aspire/modules/` is generated and any changes are clobbered. > 3. **Redirect** the requested change to `apphost.ts` — the **only** file the user > should hand-edit in a TS AppHost. > 4. If the user wants a new integration, suggest `aspire add <package>`; if they want > to change configuration, show the equivalent edit in `apphost.ts`. | ❌ Wrong | ✅ Right | |----------|---------| | Open `.aspire/modules/postgres.module.ts` and tweak the connection options | Edit `apphost.ts` and change `addPostgres('pg', { ... })` options there | | Modify a generated `.aspire/modules/*.ts` file directly | Re-run `aspire add <package>` after updating `apphost.ts` | | Comment out a line in `.aspire/modules/` to disable a resource | Remove or guard the resource declaration in `apphost.ts` | This rule applies even if the user insists, even for "one-line" changes, even for "just to test something." The TS AppHost regenerates `.aspire/modules/` deterministically; edits are unrecoverable noise. ## Guiding Principles From Aspire 13.4 ### Minimize changes to the user's code Adapt the AppHost to fit the app, not the other way around. Prefer `WithEnvironment()` to match existing environment variable names, Aspire-managed ports over fixed ports, and 1:1 Docker Compose mapping before optimizing. Do not restructure directories, rename files, or change build scripts unless the user explicitly chooses that tradeoff. ### Surface tradeoffs; do not decide silently When a small code change unlocks better Aspire integration, present both options: the zero-code-change mapping and the small-change version that enables `WithReference`, health checks, service discovery, dynamic ports, or dashboard telemetry. Ask which approach the user wants, then implement that choice without complaint. ### Verify APIs before writing AppHost code Use `aspire docs search <topic>` and `aspire docs get <slug>` for workflow guidance. Use `aspire docs api search <query> --language csharp|typescript` and `aspire docs api get <id>` for API shape. Use `aspire integration list/search` to find integrations before `aspire add`. Do not invent packages, methods, overloads, or command shapes; C# and TypeScript AppHost APIs differ. ### Keep configuration visible in the AppHost Scan `.env`, `.env.local`, `.env.development`, `secrets.json.example`, `<UserSecretsId>`, and setup scripts. Propose migrating values into AppHost parameters: connection strings become Aspire resources, API keys/tokens become secret parameters, and non-secret config becomes plain parameters or `WithEnvironment()` values. Never delete `.env` files or remove existing `UserSecretsId` entries without explicit user approval because non-Aspire workflows may still depend on them. ### Local development first This skill optimizes local development, not production deployment. Prefer persistent container lifetimes and data volumes for databases/caches, use HTTPS endpoints by default, pass endpoint references instead of hardcoded URLs, and model external SaaS URLs/API keys as parameters so they are visible in the dashboard. ### Redis TLS edge case Aspire can automatically provision TLS certificates for container resources. If Redis health checks fail with SSL/TLS handshake errors, do not fall back to `AddContainer()`. Use `WithoutHttpsCertificate()` on the Redis resource when the consuming app expects plain Redis. ## Project-Local Override If `.agents/skills/aspireify/SKILL.md` exists (installed by `aspire init` or `aspire agent init --skills aspireify`), **warn the user** that a project-local copy is present and **defer to it**. The plugin version is the fallback. ``` ⚠️ Project-local .agents/skills/aspireify/SKILL.md detected — deferring to it. ``` ## Prerequisites | Requirement | Install | |-------------|---------| | .NET 10.0 SDK (C# AppHost) | https://dotnet.microsoft.com/download | | Node.js 20+ (TS AppHost) | https://nodejs.org | | Aspire CLI | `curl -sSL https://aspire.dev/install.sh \| bash` or `dotnet tool install -g Aspire.Cli` | | Skeleton already dropped | `aspire init` produced `aspire.config.json` + AppHost stub | ## Detection — When to Activate Activate when ANY signal is present **AND** the AppHost is unwired (no resources declared beyond the stub): | Signal | How to Detect | Confidence | |--------|---------------|------------| | Skeleton just dropped | `aspire init` just ran in this session | ✅ Definitive | | Empty AppHost stub | `apphost.cs` / `Program.cs` / `apphost.ts` only contains `Build().Run()` | ✅ Definitive | | `aspire.config.json` without resources | Config present, AppHost has no `AddProject`/`addProject` | High | | User asks to "wire" / "scaffold resource graph" | Verb match: wire, scaffold, integrate, hook up, add Postgres/Redis/etc. | High | | User asks "what next after aspire init" | Direct handoff request | ✅ Definitive | | Existing repo with services + new AppHost | Repo has `.csproj`/`package.json` projects but AppHost references none | High | If the AppHost already has wired resources and the user wants to **start/stop** the app → `aspire-orchestration`. If the user wants to **deploy** → `aspire-deployment`. ## Language Support | AppHost Style | Detection | Edit Target | |---------------|-----------|-------------| | **C# SDK-style** | `.csproj` containing `<Sdk Name="Aspire.AppHost.Sdk" />` | `Program.cs` (top-level statements) | | **File-based C#** | `apphost.cs` with `#:sdk Aspire.AppHost.Sdk` and `#:package` directives | `apphost.cs` itself | | **TypeScript** | `apphost.ts` with generated `.aspire/modules/` | `apphost.ts` only — **never edit `.aspire/modules/`** | See [references/csharp-authoring.md](references/csharp-authoring.md) and [references/typescript-authoring.md](references/typescript-authoring.md). ## Workflow Phases ``` 1. SCAN → discover projects, services, dependencies, integration candidates 2. PROPOSE → resource graph + integration list, confirm with user 3. EDIT → wire AppHost, add ServiceDefaults + OTel + health checks 4. VALIDATE → aspire start --non-interactive → aspire wait <each resource> 5. DEACTIVATE → confirm clean start, hand off to aspire-orchestration ``` For the detailed, upstream-parity workflow, load these references before editing: - [apphost-wiring.md](references/apphost-wiring.md) — full AppHost wiring workflow, API lookup, endpoint/parameter patterns, validation, solution updates, and cleanup. - [docker-compose.md](references/docker-compose.md) — docker-compose migration, profiles, image mapping, ports, volumes, and `depends_on`. - [full-solution-apphosts.md](references/full-solution-apphosts.md) — large solution triage, mixed SDK boundaries, solution membership, ServiceDefaults placement, and legacy host migration. - [javascript-apps.md](references/javascript-apps.md) — JavaScript resource selection, workspace/monorepo package-manager handling, ports, scripts, and TS AppHost package config. - [opentelemetry.md](references/opentelemetry.md) — optional Node.js, Python, and Go OpenTelemetry wiring for non-.NET services. ### 1. Scan Walk the repo and inventory: | What | How | |------|-----| | .NET projects | `find . -name '*.csproj' -not -path '*/bin/*' -not -path '*/obj/*'` | | Node services | `find . -name 'package.json' -not -path '*/node_modules/*'` | | Python services | `find . -name 'pyproject.toml' -o -name 'requirements.txt'` | | Container deps in compose | `docker-compose.yml`, `compose.yaml` (Postgres? Redis? Rabbit?) | | Connection strings | grep `appsettings*.json`, `.env*`, `config/*` for `Postgres`, `Redis`, `Mongo`, `RabbitMQ`, `Cosmos`, `ServiceBus` | | Integration packages | `dotnet list package` per project; package.json `dependencies` | | Existing endpoints | hardcoded ports in `launchSettings.json`, `next.config.js`, `vite.config.ts` | Full heuristics in [references/scan-and-propose.md](references/scan-and-propose.md). ### 2. Propose Present a resource graph **before editing**. Ask clarifying questions: - "I see Postgres in `docker-compose.yml` — should I model it as `AddPostgres('db')` or use Azure Database for PostgreSQL?" - "Your React app hardcodes `http://localhost:5000` — replace with Aspire service discovery (`endpoint.url`)?" - "Your API has an `/admin` endpoint — exclude it from `WithReference()` so consumers don't see it?" ### 3. Edit Apply the proposed graph. Use the right authoring style for the AppHost language. ### 4. Validate ```bash aspire start --non-interactive --format Json aspire wait <resource> # repeat for each declared resource aspire describe --format Json # sanity check graph ``` Full validation flow + recovery in [references/validation.md](references/validation.md). ### 5. Self-Deactivate After a clean `aspire start`, announce: ``` ✅ AppHost wired and validated. Handing off to aspire-orchestration for day-to-day start/stop/wait. Aspireify is done. ``` ## Integration Discovery Catalog Map detected services → Aspire integrations. See [references/scan-and-propose.md](references/scan-and-propose.md) for the full catalog. | Detected | C# | TS | |----------|----|----| | Postgres in compose / `Npgsql` package | `AddPostgres("pg").AddDatabase("db")` | `addPostgres('pg').addDatabase('db')` | | Redis in compose / `StackExchange.Redis` | `AddRedis("cache")` | `addRedis('cache')` | | RabbitMQ | `AddRabbitMQ("mq")` (v7 client w/ pub-sub tracing) | `addRabbitMQ('mq')` | | MongoDB | `AddMongoDB("mongo")` | `addMongoDB('mongo')` | | Cosmos DB | `AddAzureCosmosDB("cosmos")` | `addAzureCosmosDB('cosmos')` | | Azure Service Bus | `AddAzureServiceBus("sb")` | `addAzureServiceBus('sb')` | | Azure Cache for Redis (Entra) | `AddAzureRedis("cache")` (now GA) | `addAzureRedis('cache')` | | Next.js frontend | `AddNextJsApp("web", "./web")` | `addNextJsApp('web', '../web')` | | Vite SPA | `AddViteApp("web", "./web")` | `addViteApp('web', '../web')` | | Plain Node app | `AddNodeApp("api", "server.js")` | `addNodeApp('api', 'server.js')` | ## Current Authoring Rules | Rule | Why | |------|-----| | Use **unified `withEnvironment(name, value)`** in TS — never the deprecated per-kind helpers (`withEnvironmentEndpoint`, `withEnvironmentParameter`, etc.) | Single API handles all value kinds; per-kind helpers are deprecated | | Use `AddNextJsApp` / `AddViteApp` over hand-rolled Dockerfiles for JS frontends | First-class lifecycle + `PublishAs*` integration | | Use `PublishAsStaticWebsite` / `PublishAsNodeServer` / `PublishAsPackageScript` for JS publish | Replaces hand-rolled Dockerfiles; SPA → static, SSR Node → NodeServer, package-script SSR → PackageScript | | Add `WithBrowserLogs()` to frontend resources for browser console + screenshots in dashboard | `Aspire.Hosting.Browsers` surfaces browser telemetry in the dashboard | | Bind every resource to a compute environment with `WithComputeEnvironment(env)` when multiple environments exist | Multi-environment deploys require explicit binding | | **Never edit `.aspire/modules/`** in TS AppHosts | Generated; edits get clobbered. Edit only `apphost.ts` | | Use `WithEndpoint("name", e => ...)` to update endpoints | Endpoint callbacks update existing endpoints rather than throwing on duplicates | | Mark admin endpoints with `ExcludeReferenceEndpoint = true` | Prevents consumers from receiving admin URLs via `WithReference()` | | Look up unfamiliar API: `aspire docs api search <query> --language csharp\|typescript` | Don't guess overloads or builder chains | ## C# vs TS Quick Reference | Concept | C# | TypeScript | |---------|----|------------| | Builder | `var builder = DistributedApplication.CreateBuilder(args);` | `const builder = await createBuilder();` | | Add project | `builder.AddProject<Projects.Api>("api")` (SDK) or `AddProject("api", "../Api/Api.csproj")` | `await builder.addProject('api', '../Api/Api.csproj')` | | Wire env var (any value type) | `.WithEnvironment("KEY", value)` | `.withEnvironment('KEY', value)` ← unified API |