om-dev-container-maintenance

name: om-dev-container-maintenance description: Maintain the VS Code Dev Container setup for Open Mercato. MUST use for ANY change to `.devcontainer/` files. Also use when the container fails to build/start, services inside misbehave, or "works locally but not in dev container". Triggers on "dev container", "devcontainer", ".devcontainer".

Dev Container Maintenance

Maintain .devcontainer/ so it stays in sync with the project's regular development requirements.

Spec & Documentation

Spec: .ai/specs/implemented/SPEC-050-2026-02-26-dev-container-setup.md
User docs: .devcontainer/README.md

Dev Container File Map

File	Purpose	When to modify
`.devcontainer/devcontainer.json`	VS Code integration: lifecycle hooks, ports, extensions, env forwarding	New ports, extensions, env vars to forward
`.devcontainer/Dockerfile`	Workspace image: Node.js, system packages, Python/Ruby/Homebrew, Claude CLI, Yarn	Node.js version bump, new system dep (`apt-get install`)
`.devcontainer/docker-compose.yml`	Services + static volumes + health checks	New service, version bump, new static volume
`.devcontainer/docker-compose.volumes.yml`	Auto-generated `dist/` volumes	Never edit — regenerated by `generate-compose-volumes.sh`
`.devcontainer/docker-compose.local.yml`	Personal overrides (gitignored) — extra bind mounts, env vars, services	Developer edits for local needs; auto-created if missing
`.devcontainer/scripts/setup-env.sh`	`.env` generation with hostname rewrites	New `.env.example` keys needing container-specific values
`.devcontainer/scripts/post-create.sh`	One-time bootstrap (install, build, generate, db init)	New build steps, changed init sequence
`.devcontainer/scripts/post-start.sh`	Per-start sync (install, migrate)	New per-start maintenance steps
`.devcontainer/scripts/generate-compose-volumes.sh`	Scans `packages/*/`, writes `docker-compose.volumes.yml`	Only if volume naming convention changes

Workflow

1. Audit (compare regular setup vs dev container)

Read and follow the checklist in references/audit-checklist.md. It covers version alignment, service parity, env var sync, package coverage, system deps, port forwarding, and build sequence.

2. Diagnose (when something is broken)

Read the guide in references/troubleshooting.md. Covers container build failures, health check failures, postCreateCommand step failures, env var mismatches, volume permissions, and DB migration conflicts.

3. Fix (apply changes)

After identifying drift or bugs:

Make the minimal change to the affected file(s) per the file map above
New .env.example keys needing container values: add sed rules to setup-env.sh with verification
New service: add to .devcontainer/docker-compose.yml with health check + forward port in devcontainer.json
Node.js or Yarn version change: update .devcontainer/Dockerfile (FROM line and corepack prepare)
Update documentation (see step 4 below) — this is mandatory for every change

4. Update documentation (mandatory after every change)

Every dev container change MUST be reflected in both documentation files. Skipping this causes drift between implementation and docs.

`.devcontainer/README.md` — user-facing docs

Update the relevant section(s):

Services table — when adding/removing/upgrading a service
Named Volumes table — when adding/removing volumes
Lifecycle Hooks section — when changing bootstrap steps
Environment Variables section — when changing env var handling
Key Design Decisions table — when making a new architectural choice
Common Tasks table — when adding new developer commands
Updating the Dev Container table — when the maintenance protocol itself changes
Troubleshooting table — when discovering new failure modes or fixes

`.ai/specs/SPEC-050-2026-02-26-dev-container-setup.md` — spec

Use the om-spec-writing skill (/om-spec-writing) to update the spec properly. At minimum:

Changelog section: Add a dated entry with a concise summary of what changed and why
Architecture / Volume Strategy / Configuration tables: Update if services, volumes, ports, or versions changed
Design Decisions table: Add a row if a new architectural decision was made
Risk Register: Add/update entries if the change introduces or mitigates a risk
Service Versions table: Update when any image tag changes
Compliance Matrix: Re-verify if the change touches areas covered by root AGENTS.md rules

The spec-writing skill ensures the update follows project conventions (TLDR, structured sections, compliance gate).

Key Comparison Points

Version sources (regular setup) vs targets (dev container):

Tool	Regular source	Dev container target
Node.js	`.nvmrc` + `package.json` engines	`.devcontainer/Dockerfile` `FROM node:<ver>-slim`
Yarn	`package.json` `"packageManager"`	`.devcontainer/Dockerfile` `corepack prepare yarn@<ver>`
PostgreSQL	`docker-compose.yml` image tag	`.devcontainer/docker-compose.yml` postgres image
Redis	`docker-compose.yml` image tag	`.devcontainer/docker-compose.yml` redis image
Meilisearch	`docker-compose.yml` image tag	`.devcontainer/docker-compose.yml` meilisearch image

Environment variable flow:

apps/mercato/.env.example
  → .devcontainer/scripts/setup-env.sh (sed rewrites)
  → apps/mercato/.env (generated, overwritten on rebuild)
  → apps/mercato/.env.local (manual overrides, never touched)

Build sequence equivalence:

Regular:   yarn install → yarn build:packages → yarn generate → yarn build:packages → yarn initialize
Container: post-create.sh steps [0]-[7] mirror this exact sequence