container-superposition 0.1.1 → 0.1.4

package/overlays/.shared/README.md

@@ -0,0 +1,43 @@
+# Shared Overlay Configurations
+
+This directory contains shared configuration fragments that can be imported by multiple overlays to reduce duplication and ensure consistency.
+
+## Structure
+
+```
+.shared/
+├── otel/               # OpenTelemetry configurations
+├── compose/            # Docker Compose patterns (healthchecks, etc.)
+└── vscode/             # VS Code extension sets
+```
+
+## Usage
+
+Overlays can import shared files by adding them to the `imports` field in `overlay.yml`:
+
+```yaml
+id: prometheus
+imports:
+    - .shared/otel/otel-base-config.yaml
+    - .shared/compose/common-healthchecks.yml
+```
+
+## Benefits
+
+- **DRY (Don't Repeat Yourself)**: Common patterns defined once
+- **Consistency**: All overlays using the same shared config stay in sync
+- **Maintainability**: Update shared config once, all overlays benefit
+- **Best Practices**: Shared configs embody proven patterns
+
+## Creating Shared Configs
+
+1. Identify common patterns across overlays
+2. Extract to appropriate `.shared/` subdirectory
+3. Update overlays to import the shared file
+4. Test that imports work correctly
+
+## Import Resolution
+
+- Imports are resolved relative to the `overlays/` directory
+- Shared files are merged into the overlay during composition
+- Files are applied in the order they are listed

package/overlays/.shared/compose/common-healthchecks.yml

@@ -0,0 +1,38 @@
+# Common Docker Compose Healthcheck Patterns
+# These can be referenced by overlays to ensure consistent healthcheck configuration
+
+healthchecks:
+    http:
+        test: ['CMD-SHELL', 'curl -f http://localhost:${PORT}/health || exit 1']
+        interval: 30s
+        timeout: 10s
+        retries: 3
+        start_period: 40s
+
+    postgres:
+        test: ['CMD-SHELL', 'pg_isready -U ${POSTGRES_USER:-postgres}']
+        interval: 10s
+        timeout: 5s
+        retries: 5
+        start_period: 10s
+
+    redis:
+        test: ['CMD', 'redis-cli', 'ping']
+        interval: 10s
+        timeout: 5s
+        retries: 5
+        start_period: 10s
+
+    mongodb:
+        test: ['CMD', 'mongosh', '--eval', "db.adminCommand('ping')"]
+        interval: 10s
+        timeout: 5s
+        retries: 5
+        start_period: 10s
+
+    mysql:
+        test: ['CMD', 'mysqladmin', 'ping', '-h', 'localhost']
+        interval: 10s
+        timeout: 5s
+        retries: 5
+        start_period: 10s

package/overlays/.shared/otel/instrumentation.env

@@ -0,0 +1,20 @@
+# OpenTelemetry Instrumentation Environment Variables
+# Common variables for language-specific auto-instrumentation
+
+# OTEL SDK Configuration
+OTEL_SERVICE_NAME=my-service
+OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317
+OTEL_EXPORTER_OTLP_PROTOCOL=grpc
+
+# Resource Attributes
+OTEL_RESOURCE_ATTRIBUTES=deployment.environment=development
+
+# Trace Configuration
+OTEL_TRACES_SAMPLER=always_on
+OTEL_TRACES_EXPORTER=otlp
+
+# Metrics Configuration
+OTEL_METRICS_EXPORTER=otlp
+
+# Logs Configuration
+OTEL_LOGS_EXPORTER=otlp

package/overlays/.shared/otel/otel-base-config.yaml

@@ -0,0 +1,30 @@
+# OpenTelemetry Base Configuration
+# This file provides common OTEL environment variables for instrumentation
+
+receivers:
+    otlp:
+        protocols:
+            grpc:
+                endpoint: 0.0.0.0:4317
+            http:
+                endpoint: 0.0.0.0:4318
+
+exporters:
+    logging:
+        loglevel: debug
+
+processors:
+    batch:
+        timeout: 10s
+        send_batch_size: 1024
+
+service:
+    pipelines:
+        traces:
+            receivers: [otlp]
+            processors: [batch]
+            exporters: [logging]
+        metrics:
+            receivers: [otlp]
+            processors: [batch]
+            exporters: [logging]

package/overlays/.shared/vscode/recommended-extensions.json

@@ -0,0 +1,14 @@
+{
+    "description": "Commonly recommended VS Code extensions across overlays",
+    "extensions": {
+        "productivity": [
+            "streetsidesoftware.code-spell-checker",
+            "usernamehw.errorlens",
+            "eamodio.gitlens"
+        ],
+        "formatting": ["editorconfig.editorconfig", "esbenp.prettier-vscode"],
+        "docker": ["ms-azuretools.vscode-docker"],
+        "yaml": ["redhat.vscode-yaml"],
+        "markdown": ["yzhang.markdown-all-in-one", "davidanson.vscode-markdownlint"]
+    }
+}

package/overlays/README.md

@@ -150,6 +150,6 @@ See [Creating Overlays Guide](../docs/creating-overlays.md) for complete documen
 
 ## Presets (Meta-Overlays)
 
-Presets are special meta-overlays that select combinations of overlays for common scenarios (web-api, microservice, docs-site, fullstack). They're located in `overlays/presets/*.yml`.
+Presets are special meta-overlays that select combinations of overlays for common scenarios (web-api, microservice, docs-site, fullstack). They're located in `overlays/.presets/*.yml`.
 
 See [Presets Guide](../docs/presets.md) and [Presets Architecture](../docs/presets-architecture.md) for detailed documentation on creating and using presets.

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: []

package/overlays/cloudflared/setup.sh

@@ -0,0 +1,49 @@
+#!/bin/bash
+# Cloudflared setup script
+# Installs cloudflared from official repository
+
+set -e
+
+echo "🌐 Setting up Cloudflared..."
+
+# Install cloudflared using official package
+echo "📦 Installing cloudflared..."
+
+# Pin to a specific version for reproducibility and security
+# Check https://github.com/cloudflare/cloudflared/releases for newer versions
+CF_VERSION="${CLOUDFLARED_VERSION:-2025.2.1}"
+
+# Detect architecture
+ARCH=$(uname -m)
+case "$ARCH" in
+    x86_64) CF_ARCH="amd64" ;;
+    aarch64 | arm64) CF_ARCH="arm64" ;;
+    *) echo "   ⚠️  Unsupported architecture: $ARCH" ; CF_ARCH="amd64" ;;
+esac
+
+CF_URL="https://github.com/cloudflare/cloudflared/releases/download/${CF_VERSION}/cloudflared-linux-${CF_ARCH}"
+curl -sSL "$CF_URL" -o /tmp/cloudflared
+sudo install -m 755 /tmp/cloudflared /usr/local/bin/cloudflared
+rm -f /tmp/cloudflared
+
+# Verify installation
+if command -v cloudflared &> /dev/null; then
+    echo "   ✅ cloudflared installed: $(cloudflared --version)"
+else
+    echo "   ❌ cloudflared installation failed"
+    exit 1
+fi
+
+echo ""
+echo "✅ Cloudflared setup complete"
+echo ""
+echo "💡 Quick start (no account required):"
+echo "   cloudflared tunnel --url http://localhost:3000"
+echo ""
+echo "💡 Named tunnel (persistent URL, requires Cloudflare account):"
+echo "   cloudflared login"
+echo "   cloudflared tunnel create my-tunnel"
+echo "   cloudflared tunnel route dns my-tunnel myapp.example.com"
+echo "   cloudflared tunnel run my-tunnel"
+echo ""
+echo "📚 Documentation: https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/"

package/overlays/cloudflared/verify.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+# Verification script for Cloudflared overlay
+# Confirms cloudflared is installed
+
+set -e
+
+echo "🔍 Verifying Cloudflared overlay..."
+echo ""
+
+# Check cloudflared
+echo "1️⃣ Checking cloudflared..."
+if command -v cloudflared &> /dev/null; then
+    echo "   ✅ cloudflared found: $(cloudflared --version)"
+else
+    echo "   ❌ cloudflared not found"
+    exit 1
+fi
+
+echo ""
+echo "✅ Cloudflared overlay verification complete"
+echo "   Quick start: cloudflared tunnel --url http://localhost:3000"

package/overlays/codex/overlay.yml

@@ -12,3 +12,4 @@ tags:
     - ai
     - code-generation
 ports: []
+minimal: true

package/overlays/direnv/README.md

@@ -214,7 +214,7 @@ dotenv_if_exists .env
 source_env_if_exists .envrc.local
 ```
 
-Create `.envrc.local` (add to `.gitignore`):
+Create `.envrc.local` (automatically gitignored at generation time):
 
 ```bash
 export PERSONAL_API_KEY="my-secret-key"
@@ -293,7 +293,7 @@ export NODE_ENV="development"
 dotenv_if_exists .env
 ```
 
-**.env** - Do NOT commit (add to `.gitignore`):
+**.env** - Do NOT commit (automatically gitignored at generation time):
 
 ```bash
 # Secrets - never commit
@@ -447,16 +447,18 @@ Settings are automatically loaded. Reload window if needed:
 
 ### Git
 
-Prevent committing secrets:
+When this overlay is selected, the following patterns are automatically added to your project’s `.gitignore` at generation time — no manual step required:
 
 ```bash
-# .gitignore
+# .gitignore (managed automatically)
 .env
 .env.local
 .envrc.local
 .direnv/
 ```
 
+This ensures environment secrets are never accidentally committed.
+
 ### Docker Compose
 
 ```bash

package/overlays/direnv/setup.sh

@@ -117,18 +117,6 @@ EOF
     echo "✓ Sample .env.example created"
 fi
 
-# Create .gitignore entries for environment files
-if [ -f .gitignore ]; then
-    if ! grep -q ".envrc" .gitignore; then
-        echo "" >> .gitignore
-        echo "# Direnv" >> .gitignore
-        echo ".envrc.local" >> .gitignore
-        echo ".env" >> .gitignore
-        echo ".env.local" >> .gitignore
-        echo "✓ Added direnv entries to .gitignore"
-    fi
-fi
-
 echo "✓ direnv setup complete"
 echo ""
 echo "💡 Usage:"