container-superposition 0.1.3 → 0.1.5

package/overlays/.presets/web-api.yml

@@ -12,13 +12,7 @@ tags: [preset, api, web, backend, observability]
 # Overlays to select
 selects:
     # Always included
-    required:
-        - postgres
-        - redis
-        - otel-collector
-        - prometheus
-        - grafana
-        - loki
+    required: []
 
     # User makes choices
     userChoice:
@@ -28,31 +22,70 @@ selects:
             options: [dotnet, nodejs, python, go, java]
             defaultOption: nodejs
 
+# Parameterized slots - users can customize these without micro-managing individual overlays
+parameters:
+    database:
+        description: 'Primary data store'
+        default: postgres
+        options:
+            - id: postgres
+              overlays: [postgres]
+              description: 'PostgreSQL relational database'
+            - id: mongodb
+              overlays: [mongodb]
+              description: 'MongoDB document database'
+            - id: mysql
+              overlays: [mysql]
+              description: 'MySQL relational database'
+            - id: none
+              overlays: []
+              description: 'No database (manage separately)'
+
+    cache:
+        description: 'In-memory cache'
+        default: redis
+        options:
+            - id: redis
+              overlays: [redis]
+              description: 'Redis cache and session store'
+            - id: none
+              overlays: []
+              description: 'No cache'
+
+    broker:
+        description: 'Message broker (optional)'
+        default: none
+        options:
+            - id: rabbitmq
+              overlays: [rabbitmq]
+              description: 'RabbitMQ AMQP message broker'
+            - id: nats
+              overlays: [nats]
+              description: 'NATS lightweight messaging'
+            - id: redpanda
+              overlays: [redpanda]
+              description: 'Redpanda Kafka-compatible streaming'
+            - id: none
+              overlays: []
+              description: 'No message broker'
+
+    observability:
+        description: 'Monitoring and observability stack'
+        default: standard
+        options:
+            - id: minimal
+              overlays: []
+              description: 'No observability tools'
+            - id: standard
+              overlays: [prometheus, grafana]
+              description: 'Metrics and dashboards'
+            - id: full
+              overlays: [otel-collector, prometheus, grafana, loki]
+              description: 'Full stack - metrics, logs, and traces'
+
 # Glue configuration - integration helpers
 glueConfig:
-    # Pre-configured environment variables
-    environment:
-        # Database connection
-        DATABASE_URL: 'postgresql://postgres:postgres@postgres:5432/myapp'
-        POSTGRES_HOST: 'postgres'
-        POSTGRES_PORT: '5432'
-        POSTGRES_DB: 'myapp'
-        POSTGRES_USER: 'postgres'
-        POSTGRES_PASSWORD: 'postgres'
-
-        # Redis connection
-        REDIS_URL: 'redis://redis:6379'
-        REDIS_HOST: 'redis'
-        REDIS_PORT: '6379'
-
-        # OpenTelemetry configuration
-        OTEL_EXPORTER_OTLP_ENDPOINT: 'http://otel-collector:4317'
-        OTEL_SERVICE_NAME: 'api-service'
-        OTEL_METRICS_EXPORTER: 'otlp'
-        OTEL_TRACES_EXPORTER: 'otlp'
-        OTEL_LOGS_EXPORTER: 'otlp'
-
-    # Suggested port mappings
+    # Suggested port mappings (actual ports depend on chosen overlays)
     portMappings:
         api: 8000
         grafana: 3000
@@ -62,40 +95,28 @@ glueConfig:
     readme: |
         ## Web API Stack
 
-        This devcontainer is configured with a complete API development stack:
-
-        ### Services
-
-        - **PostgreSQL**: Primary database (port 5432)
-        - **Redis**: Cache and session store (port 6379)
-        - **OpenTelemetry Collector**: Telemetry aggregation (ports 4317, 4318)
-        - **Prometheus**: Metrics storage (port 9090)
-        - **Grafana**: Observability dashboard (port 3000)
-        - **Loki**: Log aggregation (port 3100)
+        This devcontainer is configured for web API development. The exact services depend
+        on the parameters you chose (database, cache, broker, observability).
 
         ### Connection Strings
 
-        ```bash
-        # PostgreSQL
-        DATABASE_URL="postgresql://postgres:postgres@postgres:5432/myapp"
-
-        # Redis
-        REDIS_URL="redis://redis:6379"
+        Connection strings for each service are defined in `.devcontainer/.env.example`.
+        Copy that file to `.env` and adjust values as needed:
 
-        # OpenTelemetry
-        OTEL_EXPORTER_OTLP_ENDPOINT="http://otel-collector:4317"
+        ```bash
+        cd .devcontainer
+        cp .env.example .env
         ```
 
         ### Quick Start
 
-        1. Start your API on port 8000 (configured in this preset)
-        2. Access Grafana at http://localhost:3000 (admin/admin)
-        3. View metrics in Prometheus at http://localhost:9090
-        4. Check logs in Loki via Grafana
+        1. Start your API (default suggested port: 8000)
+        2. Access Grafana at http://localhost:3000 (admin/admin) — if observability was enabled
+        3. View metrics in Prometheus at http://localhost:9090 — if observability was enabled
 
         ### Health Checks
 
-        All services include health checks. Verify with:
+        Verify all services are running:
 
         ```bash
         docker-compose ps
@@ -103,7 +124,6 @@ glueConfig:
 
         ### Next Steps
 
-        - Configure your API to use the DATABASE_URL and REDIS_URL
-        - Add OpenTelemetry SDK to your application
+        - Configure your API to use the connection strings from `.env`
+        - Add OpenTelemetry SDK to your application (if full observability was selected)
         - Create custom Grafana dashboards for your API metrics
-        - Set up log forwarding to Loki

package/overlays/README.md

@@ -55,7 +55,13 @@ Each overlay directory contains:
 - **docker-in-docker** - Docker daemon inside container (conflicts with docker-sock)
 - **docker-sock** - Docker socket mounting (conflicts with docker-in-docker)
 - **playwright** - Browser automation with Chromium installed
-- **codex** - AI-powered code assistant
+- **codex** - OpenAI Codex CLI for AI-powered code generation and assistance
+- **spec-kit** - Specify CLI for Spec-Driven Development with any AI coding agent
+- **claude-code** - Anthropic Claude Code CLI for AI-powered development assistance
+- **gemini-cli** - Google Gemini CLI for AI-powered development assistance
+- **amp** - Sourcegraph Amp CLI for AI-powered code generation and assistance
+- **windsurf-cli** - Codeium Windsurf CLI for AI-powered development assistance
+- **opencode** - opencode AI coding agent for terminal-based development assistance
 
 ## Environment Variables
 

package/overlays/amp/README.md

@@ -0,0 +1,70 @@
+# Amp Overlay
+
+Adds the Sourcegraph Amp CLI (`amp`) for AI-powered code generation and development assistance.
+
+## Features
+
+- **Amp CLI** — Sourcegraph's AI coding agent for the terminal
+- **Codebase-aware** — Understands your entire repository context
+
+## What is Amp?
+
+Amp is Sourcegraph's AI coding agent that works directly in your terminal with deep codebase understanding:
+
+- **Code generation** — Generate new features from natural language
+- **Codebase context** — Indexed understanding of your entire codebase
+- **Multi-file edits** — Make consistent changes across the project
+- **Task execution** — Autonomous multi-step development tasks
+
+## How It Works
+
+This overlay installs `@sourcegraph/amp` globally via npm, making the `amp` command available in your devcontainer.
+
+## Common Commands
+
+```bash
+# Start an interactive session
+amp
+
+# Check version
+amp --version
+```
+
+## Use Cases
+
+- **Feature development** — Describe features, Amp implements them across the codebase
+- **Large refactors** — Make consistent changes across many files
+- **Code review** — AI-assisted code analysis
+- **Spec-Driven Development** — Works with `spec-kit` overlay via `specify init --ai amp`
+
+**Integrates well with:**
+
+- `spec-kit` — Use Amp with the SDD workflow
+- `nodejs` — Required for installation
+- `git-helpers` — Git integration for AI-generated code
+
+## Configuration
+
+Authenticate with your Sourcegraph account:
+
+```bash
+amp auth
+```
+
+## Verification
+
+```bash
+bash .devcontainer/scripts/verify-amp.sh
+```
+
+## References
+
+- [Amp by Sourcegraph](https://sourcegraph.com/amp)
+- [Sourcegraph Platform](https://sourcegraph.com/)
+
+**Related Overlays:**
+
+- `spec-kit` — Spec-Driven Development with Amp as the AI agent
+- `codex` — OpenAI Codex CLI (alternative AI assistant)
+- `claude-code` — Anthropic Claude Code (alternative AI assistant)
+- `nodejs` — Required for npm-based installation

package/overlays/amp/devcontainer.patch.json

@@ -0,0 +1,3 @@
+{
+    "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json"
+}

package/overlays/amp/overlay.yml

@@ -0,0 +1,15 @@
+id: amp
+name: Amp
+description: Sourcegraph Amp CLI for AI-powered code generation and assistance
+category: dev
+supports: []
+requires:
+    - nodejs
+suggests: []
+conflicts: []
+tags:
+    - dev
+    - ai
+    - amp
+    - sourcegraph
+ports: []

package/overlays/amp/setup.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+# amp setup script - Install Sourcegraph Amp CLI
+
+set -e
+
+echo "📦 Installing Sourcegraph Amp CLI..."
+
+# Install @sourcegraph/amp globally
+npm install -g @sourcegraph/amp
+
+# Verify installation
+if command -v amp &>/dev/null; then
+    echo "✓ Amp CLI installed successfully: $(amp --version 2>/dev/null || echo 'installed')"
+else
+    echo "✗ Amp CLI installation failed"
+    exit 1
+fi
+
+echo "✓ amp setup complete"
+echo "ℹ️  Sourcegraph Amp: https://sourcegraph.com/amp"
+echo "ℹ️  Run 'amp --help' to get started"

package/overlays/amp/verify.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+# amp overlay verification script
+
+set -e
+
+echo "🔍 Verifying amp overlay setup..."
+
+# Check if amp CLI is installed
+if ! command -v amp &>/dev/null; then
+    echo "✗ amp CLI is not installed or not in PATH"
+    exit 1
+fi
+
+echo "✓ amp CLI is installed: $(amp --version 2>/dev/null || echo 'installed')"
+
+echo ""
+echo "✅ amp overlay verification complete!"
+echo ""
+echo "💡 Tips:"
+echo "  - Run 'amp --help' to see available commands"
+echo "  - Authenticate with your Sourcegraph account"

package/overlays/claude-code/README.md

@@ -0,0 +1,83 @@
+# Claude Code Overlay
+
+Adds the Anthropic Claude Code CLI (`claude`) for AI-powered development assistance directly in the terminal.
+
+## Features
+
+- **Claude Code CLI** — Interactive AI coding assistant from Anthropic
+- **Terminal-first workflow** — Agentic coding directly from the command line
+
+## What is Claude Code?
+
+Claude Code is Anthropic's agentic coding tool that lives in the terminal. It understands your codebase and helps you code faster through natural conversation and autonomous task execution:
+
+- **Code generation** — Generate new features and components
+- **Code review** — Get feedback on your code
+- **Debugging** — Identify and fix issues
+- **Refactoring** — Improve existing code
+- **Testing** — Write and run tests
+
+## How It Works
+
+This overlay installs `@anthropic-ai/claude-code` globally via npm, making the `claude` command available in your devcontainer.
+
+## Common Commands
+
+```bash
+# Start an interactive session
+claude
+
+# Ask a one-off question
+claude "explain this function"
+
+# Authenticate with your Anthropic account
+claude auth
+
+# Check current version
+claude --version
+```
+
+## Use Cases
+
+- **Feature development** — Describe what you want to build, Claude implements it
+- **Code review** — Get AI feedback on pull requests or code changes
+- **Learning** — Understand unfamiliar codebases or concepts
+- **Refactoring** — Improve code quality with AI assistance
+- **Spec-Driven Development** — Works with the `spec-kit` overlay via `specify init --ai claude`
+
+**Integrates well with:**
+
+- `spec-kit` — Use Claude Code with the SDD workflow
+- `nodejs` — Required for installation
+- `git-helpers` — Git integration for AI-generated code
+- `pre-commit` — Quality gates for AI-generated code
+
+## Configuration
+
+Authentication is managed via the Anthropic API key:
+
+```bash
+# Set your API key
+export ANTHROPIC_API_KEY=your-api-key
+
+# Or authenticate interactively
+claude auth
+```
+
+## Verification
+
+```bash
+bash .devcontainer/scripts/verify-claude-code.sh
+```
+
+## References
+
+- [Claude Code Documentation](https://docs.anthropic.com/en/docs/claude-code)
+- [Anthropic Platform](https://console.anthropic.com/)
+
+**Related Overlays:**
+
+- `spec-kit` — Spec-Driven Development with Claude as the AI agent
+- `codex` — OpenAI Codex CLI (alternative AI assistant)
+- `gemini-cli` — Google Gemini CLI (alternative AI assistant)
+- `nodejs` — Required for npm-based installation

package/overlays/claude-code/devcontainer.patch.json

@@ -0,0 +1,3 @@
+{
+    "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json"
+}

package/overlays/claude-code/overlay.yml

@@ -0,0 +1,15 @@
+id: claude-code
+name: Claude Code
+description: Anthropic Claude Code CLI for AI-powered development assistance
+category: dev
+supports: []
+requires:
+    - nodejs
+suggests: []
+conflicts: []
+tags:
+    - dev
+    - ai
+    - claude
+    - anthropic
+ports: []

package/overlays/claude-code/setup.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+# claude-code setup script - Install Anthropic Claude Code CLI
+
+set -e
+
+echo "📦 Installing Anthropic Claude Code CLI..."
+
+# Install @anthropic-ai/claude-code globally
+npm install -g @anthropic-ai/claude-code
+
+# Verify installation
+if command -v claude &>/dev/null; then
+    echo "✓ Claude Code CLI installed successfully: $(claude --version 2>/dev/null || echo 'installed')"
+else
+    echo "✗ Claude Code CLI installation failed"
+    exit 1
+fi
+
+echo "✓ claude-code setup complete"
+echo "ℹ️  Anthropic Claude Code: https://docs.anthropic.com/en/docs/claude-code"
+echo "ℹ️  Run 'claude --help' to get started"

package/overlays/claude-code/verify.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+# claude-code overlay verification script
+
+set -e
+
+echo "🔍 Verifying claude-code overlay setup..."
+
+# Check if claude CLI is installed
+if ! command -v claude &>/dev/null; then
+    echo "✗ claude CLI is not installed or not in PATH"
+    exit 1
+fi
+
+echo "✓ claude CLI is installed: $(claude --version 2>/dev/null || echo 'installed')"
+
+echo ""
+echo "✅ claude-code overlay verification complete!"
+echo ""
+echo "💡 Tips:"
+echo "  - Run 'claude --help' to see available commands"
+echo "  - Authenticate with: claude auth"

package/overlays/cloudflared/README.md

@@ -0,0 +1,190 @@
+# Cloudflared Overlay
+
+Cloudflare Tunnel for securely exposing local services to the internet — no port forwarding or firewall configuration required.
+
+## Features
+
+- **cloudflared** - Cloudflare's tunneling daemon
+- **No account required** - Anonymous tunnels work immediately
+- **Free** - Generous free tier with no connection limits
+- **Named tunnels** - Persistent URLs with a Cloudflare account (optional)
+- **HTTPS by default** - All tunnels use TLS automatically
+
+## How It Works
+
+`cloudflared` creates an outbound-only connection from your dev container to Cloudflare's edge network. Incoming requests are routed through Cloudflare to your local service — no inbound firewall rules needed.
+
+## Quick Start
+
+```bash
+# Expose your local web server (no account required)
+cloudflared tunnel --url http://localhost:3000
+
+# Output:
+# +--------------------------------------------------------------------------------------------+
+# |  Your quick Tunnel has been created! Visit it at (it may take some time to be reachable): |
+# |  https://random-words-here.trycloudflare.com                                              |
+# +--------------------------------------------------------------------------------------------+
+```
+
+## Common Commands
+
+### Anonymous Tunnel (No Account)
+
+```bash
+# HTTP service
+cloudflared tunnel --url http://localhost:3000
+
+# HTTPS service (pass through TLS)
+cloudflared tunnel --url https://localhost:8443
+
+# Custom local port
+cloudflared tunnel --url http://localhost:8080
+```
+
+### Named Tunnel (Requires Cloudflare Account)
+
+```bash
+# 1. Log in to Cloudflare
+cloudflared login
+
+# 2. Create a named tunnel
+cloudflared tunnel create my-dev-tunnel
+
+# 3. Route traffic to a domain you own
+cloudflared tunnel route dns my-dev-tunnel dev.yourdomain.com
+
+# 4. Run the tunnel
+cloudflared tunnel run my-dev-tunnel
+
+# Run with a specific URL
+cloudflared tunnel --url http://localhost:3000 run my-dev-tunnel
+```
+
+### Configuration File
+
+Create `~/.cloudflared/config.yml` for persistent configuration:
+
+```yaml
+tunnel: my-dev-tunnel
+credentials-file: /home/user/.cloudflared/<tunnel-id>.json
+
+ingress:
+    - hostname: dev.yourdomain.com
+      service: http://localhost:3000
+    - hostname: api.yourdomain.com
+      service: http://localhost:8080
+    - service: http_status:404
+```
+
+```bash
+# Run using config file
+cloudflared tunnel run
+```
+
+### Status and Diagnostics
+
+```bash
+# Check version
+cloudflared --version
+
+# List your tunnels (requires login)
+cloudflared tunnel list
+
+# Get tunnel info
+cloudflared tunnel info my-dev-tunnel
+```
+
+## Use Cases
+
+- **Webhook testing** - Receive webhooks from GitHub, Stripe, Twilio, etc.
+- **Mobile device testing** - Test your app on real devices without complex setup
+- **Demo sharing** - Share work-in-progress with clients or colleagues
+- **OAuth callbacks** - Test OAuth flows that require a public redirect URI
+- **Long-running tunnels** - More stable than temporary ngrok tunnels
+
+## Webhook Testing Examples
+
+### GitHub Webhooks
+
+```bash
+# 1. Start tunnel
+cloudflared tunnel --url http://localhost:3000
+
+# 2. Copy the *.trycloudflare.com URL
+# 3. Add webhook in GitHub: Settings → Webhooks → Add webhook
+#    Payload URL: https://random-words.trycloudflare.com/webhook
+```
+
+### Stripe Webhooks
+
+```bash
+# Start tunnel
+cloudflared tunnel --url http://localhost:4242
+
+# Configure Stripe webhook:
+# Dashboard → Developers → Webhooks → Add endpoint
+# URL: https://random-words.trycloudflare.com/stripe/webhook
+```
+
+## Benefits vs ngrok
+
+| Feature                    | Cloudflared (this overlay) | ngrok                 |
+| -------------------------- | -------------------------- | --------------------- |
+| **Account required**       | No (anonymous tunnels)     | Yes                   |
+| **Free tier limits**       | No limits (anonymous)      | 40 connections/minute |
+| **Persistent URL (free)**  | No (random per session)    | No                    |
+| **Named tunnels**          | Yes (with account)         | Yes (paid)            |
+| **Traffic inspector UI**   | No                         | Yes (port 4040)       |
+| **Cloudflare integration** | ✅ Native                  | No                    |
+| **Connection stability**   | Very stable                | Good                  |
+
+## Security Considerations
+
+⚠️ When exposing local services to the internet:
+
+- Cloudflared exposes your local service to public internet traffic
+- Use HTTPS endpoints when possible
+- Do not expose services with sensitive data without authentication
+- Anonymous tunnels are not persistent — URL changes each session
+
+## Troubleshooting
+
+### Tunnel not starting
+
+```bash
+# Check cloudflared version
+cloudflared --version
+
+# Run with verbose logging
+cloudflared tunnel --url http://localhost:3000 --loglevel debug
+```
+
+### Connection refused
+
+Ensure your local service is running and listening on the specified port:
+
+```bash
+# Check if service is listening
+curl http://localhost:3000
+```
+
+### Named tunnel errors
+
+```bash
+# Re-authenticate
+cloudflared login
+
+# List tunnels to verify it exists
+cloudflared tunnel list
+```
+
+## References
+
+- [Cloudflare Tunnel Documentation](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/)
+- [cloudflared GitHub](https://github.com/cloudflare/cloudflared)
+- [Cloudflare Free Tunnel Guide](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/do-more-with-tunnels/trycloudflare/)
+
+**Related Overlays:**
+
+- `ngrok` - Alternative tunneling tool (conflicts with this overlay)

package/overlays/cloudflared/devcontainer.patch.json

@@ -0,0 +1,3 @@
+{
+    "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json"
+}

package/overlays/cloudflared/overlay.yml

@@ -0,0 +1,15 @@
+id: cloudflared
+name: Cloudflared
+description: Cloudflare Tunnel for securely exposing local services to the internet
+category: dev
+supports: []
+requires: []
+suggests: []
+conflicts:
+    - ngrok
+tags:
+    - dev
+    - tunneling
+    - proxy
+    - cloudflare
+ports: []