radius-app-bicep

# Radius Application Modeling Use this skill to generate a Radius application definition (`app.bicep`) from a source code repository. ## Prerequisites This skill currently supports only repositories that already contain a Dockerfile for building the application image, so a repository without one cannot be modeled. The extension normally screens this out before handing over the skill, so re-running that check is not your job. If you do find the application has no Dockerfile, stop: generate nothing, write nothing, and report this to the user verbatim. A Dockerfile means a file named `Dockerfile`, `Dockerfile.<suffix>`, or `<prefix>.Dockerfile`, matched case-insensitively on the file name, at the repository root or in a service subdirectory. Ignore any that sits inside a vendored, generated, or tooling directory — `node_modules`, `dist`, `build`, `coverage`, `.next`, `.turbo`, `venv`, `.venv`, or any other dot-directory apart from `.radius` and `.github`. A `.devcontainer` image builds the development environment, not the application, so it does not count. > I could not find a Dockerfile in this repository. I can only create application definitions for containerized applications. Add a Dockerfile first, then I can create an application definition. ### Identifying the application A repository with several Dockerfiles is normally still one application. A microservices repository builds many images, and this skill models a microservices repository into a single `Radius.Core/applications` named after the repository, with the services wired to each other through the addressing rules in [connection-conventions.md](references/connection-conventions.md). A Dockerfile count is never decisive on its own, and it is never by itself a reason to put a question to the user. Nor does a Dockerfile prove there is a service to model: it may build a CI image, a migration or tooling image, an unused example, or an alternative to another one. A root workspace manifest such as `pnpm-workspace.yaml` or `go.work` describes how the repository is organized, not that its projects form one application — independent applications use those tools too, so weigh it against the source rather than concluding from it. Establish from the source which directories hold application services that share a runtime and deploy together, and model those as one application. Ask the user only when, after reading the source, you cannot identify an application at all. That happens in two cases: - the repository holds more than one **independent** application, which a single definition cannot represent, or - nothing in the repository is an application — for example the Dockerfiles build only tooling or CI images. In either case, ask exactly: > I looked through the repository but could not identify an application or application resources. Which directory contains your application source code and Dockerfile? Then stop, and write nothing: no `.radius/app.bicep`, no `.radius/bicepconfig.json`, no origin record, no branch, no commit. Do not guess a directory on the user's behalf or model one candidate to "make progress" — a directory you chose yourself is not an answer to the question you just asked. The user replies with a directory and asks for analysis again, which scopes the next run to it; the skill already supports a subdirectory through the `build.source` rule. ## Response When asked to model a repository: 1. Generate the application definition into a staging directory and publish it only once the whole run is complete (see [Staged runs](#staged-runs)). Never write `.radius/app.bicep`, `.radius/bicepconfig.json`, the origin record, or a custom-type artifact directly into `.radius/`, and never `git add` anything yourself: the promote script publishes and stages the run. Do NOT push, and do NOT open a pull request: modeling only writes and stages the files locally. The application graph renders from the on-disk working tree, so no push is needed to preview it, and pushing to a remote is a deployment concern handled later, not part of modeling. 2. In your chat reply, give a one-line intro naming the app (e.g. "I'll create an application definition for `todo-list-app`."), then a short, natural summary of the resources you identified, a brief list such as "Container: `todo-list-app`", "MySQL database", "Secret for DB credentials". A sentence or two of reasoning is fine; don't dump raw source analysis or the full file contents. If external-client ingress was considered but omitted, state why. Describe only what you actually did (that the run published and staged the model files in the working tree); do not claim the application graph or canvas is rendering, since you cannot observe that. If a graph view is opened and shows an error or empty state, report that honestly instead of asserting success. Keep the reply about the user's application and its resources; do not name internal skill or reference files (for example, reference examples the skill consulted). ## Node runtime boundary Every bundled script in this skill runs under a Node.js interpreter, and `<loaded-node>` is the absolute path of the one the Radius extension resolved on this machine. Always invoke a script through it — `"<loaded-node>" "<loaded-skill-base>/scripts/<script>.mjs"` — and never as a bare `node`, `npx`, or `npm` command. The Copilot app embeds its Node runtime inside its own executable and exposes no `node` binary, so the shell you run commands in frequently has none on `PATH`; `<loaded-node>` is the interpreter that does exist. In PowerShell, invoke it with the call operator: `& "<loaded-node>" "<loaded-skill-base>/scripts/<script>.mjs"`. The extension guarantees `nodeCommand` is an absolute path with no shell metacharacters in it, so quoting it is enough; never expand, rewrite, or concatenate it into a larger command string, and never pass it through `eval`, `sh -c`, or `Invoke-Expression`. Never download, install, unpack, build, or vendor a Node.js runtime, and never install `nvm`, a package manager, or any other tool in order to obtain one. Installing software on the user's machine is not part of modeling, it is never done without the user asking for it, and it is unnecessary here because the extension already resolved the interpreter. Do not search for or substitute another runtime either. If the handoff reports `nodeCommand: null`, or `<loaded-node>` is missing, empty, still the literal placeholder, or fails to run, the run cannot proceed: abort any staged run (see [When a step fails](#when-a-step-fails)), report exactly what failed, state that nothing was written, and ask the user to install Node.js 18 or newer — or to make their existing installation visible to the Copilot app — then stop and wait. Only a fresh user request may start another run. ## Radius CLI execution boundary Never invoke `rad` or `rad.exe` directly from PowerShell, a shell, a subprocess, or a delegated agent. Use `"<loaded-node>" "<loaded-skill-base>/scripts/show-radius-type.mjs"` to resolve predefined Radius type definitions. Compile the generated application definition with `"<loaded-node>" "<loaded-skill-base>/scripts/validate-bicep.mjs" <staging-dir>/app.bicep`; the checker uses only the extension-managed Bicep and fails on every compiler warning or error. Graph validation must go through the Radius canvas and its tools: open `canvasId: "radius"` with `instanceId: "radius-panel"`, pass the current session repository as `repo` in `owner/repo` form, and use the current Copilot worktree branch. The extension honors an existing executable `RADIUS_RAD_BINARY` as a developer-owned override; otherwise it runs its managed binary from `%USERPROFILE%\.radius\ai-extensions\bin\rad.exe` on Windows or `$HOME/.radius/ai-extensions/bin/rad` on macOS/Linux, downloading it when absent and attempting a best-effort upgrade when older than the latest release (offline/API failures keep the installed binary; set `RADIUS_RAD_SKIP_VERSION_CHECK` to skip the version check). It does not resolve `rad` from `PATH` or `.rad/bin`. Diagnose graph failures only from the Radius extension log; never reproduce them with a direct CLI command or through another agent. `validate-bicep.mjs` has this exit-code contract: | Exit code | Meaning | Required action | |-----------|--------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `0` | Validation completed with valid compiler output and no compiler warnings, compiler errors, or checker policy violations. | Continue the validation checklist. Only after it is complete, write the origin record and publish the staged run. | | `1` | Validation completed and found actionable compiler or checker policy diagnostics about the model. | Repair the staged model and rerun the checker within the repair budget. Only exit `1` permits a model edit in response to checker output. | | `2` | Validation was unavailable, incomplete, or refused before a reliable verdict. | Run `"<loaded-node>" "<loaded-skill-base>/scripts/promote-app-model.mjs" --abort --staging "<staging-dir>"`, report the exact checker failure, and state that no application model was written. Do not edit the model based on this result, write `app.origin.json`, publish, or claim that the model compiled. Do not download, install, replace, relocate, or search for another Bicep binary. The Radius extension owns the managed binary lifecycle. Never continue or manually restart the current staged run; after the underlying failure is corrected, only a user request may start a fresh modeling run. | These codes apply only to `validate-bicep.mjs`. The promote script has a separate exit `2` meaning documented under [Staged runs](#staged-runs): it published the files, but `git add` failed. When Bicep exits successfully, the checker reports its warnings together with every compiled-output policy finding from the same attempt before returning `1`. If compiled JSON or required policy evidence is unusable, the checker returns `2` even when it also printed a compiler warning, because it could not produce a complete verdict. Compiler diagnostics retain their primary source location as `uri:line:column` when Bicep supplies a usable column, or `uri:line` when it does not. A missing location is not inferred from another diagnostic or secondary location. Columns improve location accuracy only; they do not change validation decisions or the repair budget. If `show-radius-type.mjs` fails while locating, querying, or validating the selected Radius CLI or while deriving its extension reference, stop the modeling run, run `"<loaded-node>" "<loaded-skill-base>/scripts/promote-app-model.mjs" --abort --staging "<staging-dir>"`, and report the exact error. This includes a missing binary, invalid or incomplete version JSON, a missing or unsupported stamped release identity, a noncanonical commit, and a pull-request release, for which no Radius Bicep types are published. A CLI-resolution failure is not permission to repair the toolchain: never download, install, upgrade, downgrade, copy, move, rename, back up, delete, or replace a `rad` binary; never change or unset `RADIUS_RAD_BINARY` or `RADIUS_RAD_SKIP_VERSION_CHECK`; and never search `PATH`, `.rad/bin`, or another location for a released fallback. The extension alone owns its managed binary lifecycle. Use a different binary only after the user explicitly changes their configuration and requests a new modeling run. ## Workflow 1. Start the run with `"<loaded-node>" "<loaded-skill-base>/scripts/promote-app-model.mjs" --begin`, which prints the staging directory to write everything into (see [Staged runs](#staged-runs)). Then select one runnable deployment profile. Treat explicit user, scenario, and target-repository deployment requirements for Radius types, resource-name parameters, workload roles/count, native configuration keys, secret bindings, provider profile, protocol values, and connection names as acceptance criteria. Verify that the pinned source supports that profile; do not silently replace it with an easier default or optional backend. 2. Build and maintain an internal requirement ledger. Record every acceptance criterion and planned resource property read or write with its source evidence and consuming workload setting. After type resolution, add the exact `resources[].apiVersion` and recursive `resources[].schema` path returned by `show-radius-type.mjs`, any `readOnly` or `writeOnly` restriction, and the separate Recipe and target-Environment evidence required for generated values. Use the ledger for reasoning and validation; do not print it or add it as Bicep comments. Follow [runtime-contract.md](references/runtime-contract.md). 3. Inventory every executable workload and backing service in the selected profile from manifests, Dockerfiles, compose/Helm files, entrypoints, source configuration reads, client initialization, and referenced config files. Treat web, worker, producer, consumer, migration, scheduler, and sidecar roles separately. Model a backing service only when source evidence proves it is mandatory for the selected startup/configuration path; a repo-wide optional dependency, extra, adapter, test, or example does not become a resource. After completing this inventory, decide external-client ingress using only the selected profile's startup and configuration chain and the [route authoring rule](#appbicep-structure-mandatory-order). Ask and stop if it is ambiguous; do not revisit the decision with files from an unselected profile. 4. Extract each workload's runtime contract: image/build context and target platform, entrypoint and arguments, listener and ports, required environment/configuration including parser coercion and unset behavior, secrets, writable storage, dependencies, wire protocols, TLS, authentication/bootstrap setup, and feature-critical configuration. Inspect CLI flags and structured fields as well as environment variables. 5. Map every selected backing service to a Radius type with [component-catalog.md](references/component-catalog.md), using [architecture-patterns.md](references/architecture-patterns.md) only as context. Report unsupported essential components instead of substituting unrelated types. 6. After the workload, backing-service, ingress, image-publishing, and secret inventory is complete, but before authoring Bicep, resolve every planned predefined type in one `show-radius-type.mjs` batch as described in [Resource Type Resolution](#resource-type-resolution). Apply the resource-specific structure rules before this call so companion predefined resources are included in the same batch. Unless target evidence explicitly proves an unauthenticated image registry, planning `Radius.Compute/containerImages` also plans the single `Radius.Security/secrets` registry-push companion described below. Preserve and inspect the complete returned JSON. Use each returned `type`, `apiVersion`, `schema`, and `recipe`, and handle every nonzero exit or `notFound` entry as described there. The script creates or merges the staged `bicepconfig.json` and owns its `radius` alias. The result supplies type-schema evidence and, when available, managed-release default Recipe evidence. Before authoring, apply the [Credential shape](references/secrets-handling.md#credential-shape) check. Use an available `recipe.definition` as the managed-default Azure Recipe profile unless explicit target evidence selects another Recipe; use that selected Recipe to decide whether a credential exists and inspect every credential representation it exposes. For each predefined type whose resolved Recipe meets the applicability check in [azure-provider-value-rules.md](references/azure-provider-value-rules.md), apply those rules to every property that the Recipe copies into an Azure name, administrator login, or AI model setting. Do not apply those Azure rules to AWS, Kubernetes, or an unverified custom Recipe. Prefer a direct shape match. When an aggregate output is incompatible or unknown, consider schema-declared discrete outputs and safe runtime composition before reporting a blocker; when the client needs parts, consider a proven runtime decomposition path. A package name without a checked-in consumer is not evidence, but an exact pinned dependency together with the checked-in call site that passes the value to that client's configuration API identifies the parser contract and permits using that client's documented syntax. Combine that client evidence with selected-profile literals, checked-in parser code, schema descriptions, and the selected Recipe's auth and output mappings. Treat compatibility as unknown only after direct binding and every supported composition or decomposition path have been considered. Stop on missing Recipe behavior or a remaining incompatible or unknown shape. Verify target-Environment registration, Recipe declarations outside the returned definition, and other application runtime behavior separately. 7. Build the application's own workloads from the repository Dockerfile via `Radius.Compute/containerImages`; this is the default path, and a repository without a Dockerfile is unsupported (see [Prerequisites](#prerequisites)). Require a complete, practical build context and pin `build.source` to the exact modeled checkout or an explicit immutable release tag. When the ref is a commit, use its full 40-character SHA in `?ref=`; never use an abbreviated SHA. The image `tag` may remain abbreviated because it is not a Git ref. Resolve the exact `containerImages` Recipe: verify omitted optional inputs, set a Docker-valid immutable `tag` only when required by that contract, decide `build.platforms` per image with the [Choosing build.platforms](references/bicep-structure-rules.md#choosing-buildplatforms) procedure, and preserve required Git metadata with schema-supported build arguments. Use a pinned published image only for a genuinely third-party/backing container, never for the application's own code. Map every runtime value using [connection-conventions.md](references/connection-conventions.md), [secrets-handling.md](references/secrets-handling.md), and [bicep-structure-rules.md](references/bicep-structure-rules.md).