---
name: gen-devcontainer
description: >
  Generate a `.devcontainer/devcontainer.json` keyed to the project's
  primary language so `gh codespace create` (or VS Code's "Reopen in
  Container") gives anyone on the team a ready-to-go env with the
  right runtime, GH CLI, git-lfs, and language-tier VS Code
  extensions pre-installed. Preview-by-default; idempotent on apply
  (no-op on identical bytes, diff-and-refuse on divergence unless
  `--force-overwrite`).
  TRIGGER when the user says "add a devcontainer", "set up
  codespaces", "scaffold devcontainer.json", "reopen in container",
  "configure dev environment", "containerized dev env", "make this
  work in codespaces", "add VS Code container", "wire up
  devcontainer", "/nyann:gen-devcontainer". Also trigger when a user
  asks "how do I run this in Codespaces" and there's no
  `.devcontainer/` directory yet.
  Do NOT trigger on "build a Docker image for production" — that's
  a Dockerfile concern outside devcontainer scope. Do NOT trigger on
  "fix my devcontainer build" — that's debugging an existing setup,
  not generating one (read the file with the user instead).
arguments:
  - name: language
    description: Primary language — one of node, python, go, rust, dart, java, dotnet, php, ruby, swift, elixir, cpp. Maps from StackDescriptor.primary_language (typescript/javascript → node, csharp → dotnet).
  - name: name
    description: Devcontainer display name (surfaced in 'Open in Container' picker). Default is the repo basename when --target is supplied, otherwise `<language>-devcontainer`.
    optional: true
  - name: target
    description: Path to the repo. Required only when `--apply` is set.
    optional: true
  - name: apply
    description: Write the devcontainer.json to `<target>/.devcontainer/devcontainer.json`. Default is preview-to-stdout.
    optional: true
  - name: force-overwrite
    description: Overwrite an existing devcontainer.json whose content differs. Without it, the script prints a diff and exits 3.
    optional: true
  - name: port
    description: Repeatable. Forward a port from the container to the host (1-65535). Common picks - 3000/4200/5173 web dev, 8000/8080 APIs.
    optional: true
  - name: feature
    description: Repeatable. Extra devcontainer feature ref to merge onto the base set (gh CLI, git-lfs, common-utils). Always include a version pin.
    optional: true
  - name: extension
    description: Repeatable. Extra VS Code extension ID (`publisher.extension` format) to merge onto the per-language base set.
    optional: true
  - name: post-create-command
    description: Override the default per-language postCreateCommand. Empty string disables postCreateCommand entirely.
    optional: true
  - name: cpus
    description: Codespaces hostRequirements.cpus (2-32). Default unset (lets Codespaces pick).
    optional: true
  - name: memory
    description: Codespaces hostRequirements.memory (e.g. `4gb`, `8GiB`). Default unset.
    optional: true
  - name: storage
    description: Codespaces hostRequirements.storage (e.g. `16gb`, `32GiB`). Default unset.
    optional: true
---

# gen-devcontainer

Wraps `bin/gen-devcontainer.sh`. Emits a devcontainer.json; preview-
by-default; idempotent on apply.

## When to trigger

- User wants a Codespaces-ready repo and there's no `.devcontainer/`
  directory yet.
- User wants to refresh an existing devcontainer.json after upgrading
  nyann (base image tags + extension lists shift with the
  `snapshot_version` comment in the file).
- User wants to add forwarded ports / cpus / memory to an existing
  devcontainer (use `--port 3000 --cpus 4 --memory 8gb`).

## When NOT to trigger

- User wants a **production Dockerfile** — that's an entirely
  different concern; devcontainer.json is dev-environment only.
- User wants to **debug** a broken devcontainer build — open the
  existing file with them; this skill generates fresh, not diagnoses.
- User is on a non-Codespaces, non-VS Code editor — the file still
  works under JetBrains' Dev Containers plugin and `devcontainer
  open` (CLI), but flag the broader VS Code-first defaults.

## Picking the language

Read `StackDescriptor.primary_language` from `bin/detect-stack.sh`:

| StackDescriptor.primary_language | --language |
|---|---|
| `typescript` / `javascript` | `node` |
| `python` | `python` |
| `go` | `go` |
| `rust` | `rust` |
| `dart` | `dart` |
| `java` / `kotlin` | `java` |
| `csharp` / `dotnet` | `dotnet` |
| `php` | `php` |
| `ruby` | `ruby` |
| `swift` | `swift` |
| `elixir` | `elixir` |
| `cpp` / `c` | `cpp` |

For polyglot monorepos (`workspaces[]` present), pick the language of
the most-important workspace OR ask the user — running multiple
devcontainers from a single repo is uncommon and confusing.

## Preview, then apply

Always preview first. Show the rendered JSON; wait for confirmation:

```
bin/gen-devcontainer.sh --language python --name my-app
```

Then on confirmation:

```
bin/gen-devcontainer.sh --language python --name my-app \
  --target . --apply
```

If the destination already matches: log "unchanged" and exit. If it
differs: print the unified diff to stderr, exit 3, prompt the user
before re-running with `--force-overwrite`.

## Output shape

`.devcontainer/devcontainer.json` containing:

- `$schema` pointing at the official devcontainer spec
- `$comment` tagging the nyann snapshot version
- `name` (display name in 'Open in Container' picker)
- `image` (per-language, pinned to a major:minor tag)
- `features` (gh CLI, git-lfs, common-utils — version-pinned)
- `customizations.vscode.extensions` (per-language pack + gitlens + git-graph)
- `postCreateCommand` (per-language dep install — `npm ci`, `uv sync`, `cargo fetch`, etc.)
- `forwardPorts` (when `--port` flag(s) supplied)
- `hostRequirements` (when `--cpus` / `--memory` / `--storage` supplied)

## Defaults explained

- **Base image**: Microsoft devcontainers/<lang> images where they
  exist (well-maintained, security-scanned, multi-arch). Vendor
  images for Dart / Swift / Elixir where no MS variant exists.
- **Image tag**: pinned to `major:minor`, NOT a digest. Operators who
  need byte-reproducible builds should pin to a digest by hand; the
  Docker ecosystem of `gen-dependency-updater` can roll the tag.
- **Extensions**: per-language language pack + `gitlens` + `git-graph`
  baseline. Conservative pick; extend via `--extension`.
- **Features**: `github-cli:1` + `git-lfs:1` + `common-utils:2`,
  always with a version pin so floating tags can't quietly re-broadcast.
- **postCreateCommand**: best-effort install that no-ops when the
  expected manifest is missing (so the file works in a partially-
  scaffolded repo). Override with `--post-create-command` for non-
  standard package managers (e.g. pnpm rather than npm).

## Reading the output back

When previewing:
- Surface the base image (the operator may want to swap to an
  org-internal mirror).
- Surface the postCreateCommand (so they can spot install commands
  that don't fit their workflow).
- Suggest `--port` flags if the user mentioned a dev-server port in
  the conversation.

When applying:
- Confirm the dest path didn't already exist (or that the diff was
  intentional if `--force-overwrite` was used).
- Suggest a follow-up `gh codespace create` invocation if the user
  asked for Codespaces specifically.