Version 0.1.4

[0.1.4] - 2026-02-26

Added

• Keycloak overlay — Open-source identity and access management for local OAuth2/OIDC development

  • Runs as a Docker Compose service on port 8180 (avoids collision with common app servers)
  • Automatically requires and integrates with the postgres overlay as its database backend
  • Exposes OIDC discovery at /realms/master/.well-known/openid-configuration
  • KEYCLOAK_HOST, KEYCLOAK_PORT, and KEYCLOAK_ISSUER wired into the dev container via remoteEnv

• Mailpit overlay — Email testing tool that captures all outbound email locally

  • SMTP server on port 1025 (no authentication required in dev mode)
  • Web UI on port 8025 for browsing captured emails
  • REST API at /api/v1/messages for automated test assertions
  • SMTP_HOST, SMTP_PORT, and MAILPIT_URL wired into the dev container via remoteEnv

• gRPC Tools overlay — Protocol Buffers and gRPC development toolchain

  • Installs protoc (via system packages), buf CLI, and grpcurl (from official GitHub releases, multi-arch)
  • VS Code extensions: vscode-proto3 and vscode-buf
  • Works with all base stacks (plain and compose)

• Cloudflared overlay — Cloudflare Tunnel for securely exposing local services to the internet

  • Anonymous tunnels work immediately with no account required
  • Named tunnels support persistent URLs with a Cloudflare account
  • Conflicts with ngrok overlay (bidirectional — both overlays declare the conflict)
  • Pinned to a specific release version for reproducibility

• Service reference exports — Two convenience files are now auto-generated during init and regen for projects that include service overlays

  • services.md — Consolidated service reference with connection info, connection strings (URIs), code examples (Node.js, Python) for common services, common CLI commands, port offset documentation, and a troubleshooting section
  • env.local.example — Optional-overrides template derived from each overlay's .env.example, with all values commented out and grouped by service — copy to .env and uncomment only what you need to customize
  • Both files are tracked in the file registry and cleaned up on regeneration alongside other generated files

• Git-aware backup defaults — Backups are now skipped automatically when the target directory is inside a git repository (git already tracks history), and created by default when it is not

  • --backup flag forces a backup even inside a git repo
  • --no-backup flag suppresses a backup even outside a git repo
  • Auto-detection uses git rev-parse --git-dir; falls back to walking up the directory tree looking for a .git folder when the git command is unavailable

• Automatic .gitignore management — Generated projects now include tool-specific .gitignore entries automatically; overlay-provided patterns are merged into your project root .gitignore at generation time

  • Entries from each overlay are grouped under a labelled comment for easy identification
  • Running generation again never duplicates patterns already in your .gitignore
  • Overlay-provided ignore rules are always applied to the project root .gitignore (never to files inside .devcontainer/), keeping generated configuration isolated from your application's source ignores

• direnv overlay: secrets and env files are gitignored automatically — .envrc.local, .env, .env.local, and .direnv/ are now excluded from git immediately after generation — no need to start the container first

• Python overlay: workspace virtual environment (.venv) — The Python overlay now sets up a .venv virtual environment in your project root on container creation

  • VS Code automatically uses the workspace .venv as the Python interpreter
  • All project dependencies are installed into the venv (requirements.txt, requirements-dev.txt, pyproject.toml, setup.py)
  • .venv/, __pycache__/, *.pyc, and other Python artifacts are added to .gitignore automatically

• Preset parameterization — Customize presets with high-level choices without micro-managing individual overlays

  • New parameters field in preset definitions maps choices to sets of overlays
  • web-api preset now parameterized: database, cache, broker, observability slots
  • microservice preset now parameterized: broker, observability slots
  • Interactive questionnaire asks for each parameter value with descriptions and defaults
  • --preset <id> CLI flag pre-selects a preset and skips the preset selection prompt
  • --preset-param <key=value> CLI flag pre-fills parameter values (repeatable)
  • Pre-filled parameters skip their interactive prompt; unfilled ones are still asked
  • Invalid parameter values produce helpful error messages listing valid options
  • explain <preset-id> now shows parameters, options, defaults, and usage examples
  • Example: container-superposition init --preset web-api --preset-param broker=nats --preset-param observability=full

• plan --diff — Compare planned output vs existing .devcontainer/ configuration before applying changes

  • Shows files to be created, modified, unchanged, and removed
  • Generates colored unified diff for devcontainer.json (loads base template + applies overlay patches)
  • Detects overlay changes (added/removed) by comparing with existing superposition.json manifest
  • Detects port changes (added/removed) derived from overlay comparison
  • Lists preserved custom files in custom/ directory
  • --output <path> to compare against a custom existing config path (default: ./.devcontainer)
  • --diff-format json for machine-readable output (also via --json)
  • --diff-context <lines> to control diff context lines (default: 3)
  • Example: container-superposition plan --stack compose --overlays postgres,redis --diff