container-superposition 0.1.1

package/overlays/ngrok/setup.sh

@@ -0,0 +1,125 @@
+#!/bin/bash
+# ngrok setup script
+
+set -e
+
+echo "🌐 Setting up ngrok..."
+
+# Install ngrok using official apt repository (provides signed packages)
+echo "📦 Installing ngrok from official repository..."
+
+# Add ngrok's GPG key and repository
+curl -sSL https://ngrok-agent.s3.amazonaws.com/ngrok.asc \
+    | sudo tee /etc/apt/trusted.gpg.d/ngrok.asc >/dev/null
+
+echo "deb https://ngrok-agent.s3.amazonaws.com buster main" \
+    | sudo tee /etc/apt/sources.list.d/ngrok.list
+
+# Update and install
+sudo apt-get update -qq
+sudo apt-get install -y ngrok
+
+# Verify installation
+if command -v ngrok &> /dev/null; then
+    echo "✓ ngrok installed: $(ngrok version)"
+else
+    echo "✗ ngrok installation failed"
+    exit 1
+fi
+
+# Create sample ngrok configuration
+mkdir -p "$HOME/.config/ngrok"
+if [ ! -f "$HOME/.config/ngrok/ngrok.yml" ]; then
+    cat > "$HOME/.config/ngrok/ngrok.yml" << 'EOF'
+# ngrok configuration file
+# Visit https://dashboard.ngrok.com/get-started/your-authtoken to get your authtoken
+# Then run: ngrok config add-authtoken YOUR_TOKEN
+
+version: "2"
+
+# Uncomment and set your authtoken
+# authtoken: YOUR_AUTHTOKEN_HERE
+
+# Region (us, eu, ap, au, sa, jp, in)
+region: us
+
+# Console UI settings
+console_ui: true
+console_ui_color: transparent
+
+# Log settings
+log_level: info
+log_format: json
+log: /tmp/ngrok.log
+
+# Tunnel definitions
+tunnels:
+  # HTTP tunnel example
+  web:
+    proto: http
+    addr: 3000
+    # Optional: custom subdomain (requires paid plan)
+    # subdomain: myapp
+    # Optional: custom domain (requires paid plan)
+    # hostname: myapp.example.com
+    # Optional: basic auth
+    # auth: "user:password"
+    # Optional: inspect traffic
+    inspect: true
+
+  # HTTPS tunnel example
+  api:
+    proto: http
+    addr: 8080
+    inspect: true
+
+  # TCP tunnel example (databases, SSH, etc.)
+  database:
+    proto: tcp
+    addr: 5432
+
+  # TLS tunnel example
+  secure:
+    proto: tls
+    addr: 443
+
+# Webhook endpoints for event notifications (requires paid plan)
+# webhooks:
+#   - name: "webhook-handler"
+#     url: "https://example.com/ngrok-events"
+#     events:
+#       - "tunnel_started"
+#       - "tunnel_stopped"
+EOF
+    echo "✓ Sample ngrok.yml created at ~/.config/ngrok/ngrok.yml"
+fi
+
+# Create sample helper scripts
+mkdir -p "$HOME/.local/bin" 2>/dev/null || true
+
+cat > "$HOME/.local/bin/ngrok-web" << 'EOF'
+#!/bin/bash
+# Quick script to expose local web server
+
+PORT=${1:-3000}
+echo "🌐 Exposing localhost:${PORT} via ngrok..."
+ngrok http ${PORT}
+EOF
+
+chmod +x "$HOME/.local/bin/ngrok-web" 2>/dev/null || true
+
+echo "✓ ngrok setup complete"
+echo ""
+echo "⚠️  IMPORTANT: Authenticate ngrok before use"
+echo "   1. Sign up at https://dashboard.ngrok.com/signup"
+echo "   2. Get your authtoken from https://dashboard.ngrok.com/get-started/your-authtoken"
+echo "   3. Run: ngrok config add-authtoken YOUR_TOKEN"
+echo ""
+echo "💡 Quick start:"
+echo "   ngrok http 3000              # Expose localhost:3000"
+echo "   ngrok http 8080 --subdomain myapp  # Custom subdomain (paid)"
+echo "   ngrok tcp 22                 # Expose SSH"
+echo "   ngrok start web              # Start named tunnel from config"
+echo ""
+echo "📚 Configuration: ~/.config/ngrok/ngrok.yml"
+echo "🔍 Web interface: http://localhost:4040"

package/overlays/nodejs/README.md

@@ -0,0 +1,192 @@
+# Node.js Overlay
+
+Adds Node.js LTS with TypeScript, modern tooling, and customizable global packages.
+
+## Features
+
+- **Node.js LTS** (currently 20.x)
+- **Package Managers:** npm (built-in), pnpm (via global-packages.txt)
+- **VS Code Extensions:**
+    - ESLint (dbaeumer.vscode-eslint)
+    - Prettier (esbenp.prettier-vscode)
+    - npm Intellisense (christian-kohler.npm-intellisense)
+- **Automatic install:** Runs `npm install` on container creation
+- **Global Packages:** Configured via `global-packages.txt`
+
+## Customizing Global Packages
+
+The overlay includes a customizable `global-packages.txt` file in `.devcontainer/`:
+
+**`.devcontainer/global-packages.txt`:**
+
+```
+# Node.js Global Packages
+# Format: one package per line, with optional version
+# Example: typescript@5.3.0
+
+# pnpm - Fast package manager
+pnpm
+
+# Add your custom global packages here
+typescript
+ts-node
+nodemon
+eslint
+prettier
+```
+
+### Version Pinning
+
+Pin specific versions using `@`:
+
+```
+typescript@5.3.0
+pnpm@8.10.0
+eslint@8.50.0
+```
+
+**Rebuild container** after editing to install new packages.
+
+## Common Global Packages
+
+### Development Tools
+
+- `pnpm` - Fast, disk-efficient package manager
+- `typescript` - TypeScript compiler
+- `ts-node` - TypeScript execution engine
+- `tsx` - Modern TypeScript runner
+
+### Process Management
+
+- `nodemon` - Auto-restart on file changes
+- `pm2` - Production process manager
+- `concurrently` - Run multiple commands
+
+### Code Quality
+
+- `eslint` - JavaScript linter
+- `prettier` - Code formatter
+- `@biomejs/biome` - All-in-one toolchain
+
+### Build & Bundle
+
+- `vite` - Modern build tool
+- `esbuild` - Fast bundler
+- `webpack-cli` - Webpack command line
+
+### Testing
+
+- `vitest` - Fast test runner
+- `jest` - Testing framework
+
+## Project Structure
+
+Works with:
+
+- **package.json** - Project dependencies
+- **package-lock.json** (npm)
+- **pnpm-lock.yaml** (pnpm)
+- **yarn.lock** (yarn)
+
+## Automatic Setup
+
+On container creation:
+
+1. ✅ Installs global packages from `global-packages.txt`
+2. ✅ Runs `npm install` (if package.json exists)
+3. ✅ Verifies installations
+
+## Common Workflows
+
+### Using pnpm
+
+```bash
+pnpm install        # Install dependencies
+pnpm add express    # Add dependency
+pnpm run dev        # Run dev script
+```
+
+### TypeScript Development
+
+```bash
+# Global tools approach
+npm install -g typescript ts-node
+tsc --init
+ts-node src/index.ts
+
+# Local tools approach (recommended)
+npm install --save-dev typescript ts-node
+npx tsc --init
+npx ts-node src/index.ts
+```
+
+### Running Multiple Processes
+
+With `concurrently` installed globally:
+
+```bash
+concurrently "npm run api" "npm run web"
+```
+
+## Package Manager Choice
+
+### npm (Default)
+
+- ✅ Built-in, no setup
+- ✅ Widely compatible
+- ❌ Slower, larger node_modules
+
+### pnpm (Recommended)
+
+- ✅ Fast, efficient disk usage
+- ✅ Strict dependency resolution
+- ✅ Workspace support
+- ⚠️ Some compatibility edge cases
+
+### yarn
+
+- Add to `global-packages.txt`: `yarn`
+
+## Best Practices
+
+1. **Prefer local over global** - Use `devDependencies` in package.json
+2. **Lock file** - Commit package-lock.json / pnpm-lock.yaml
+3. **Use `.nvmrc`** or `engines` in package.json for Node version
+4. **scripts in package.json** - Better than global commands
+
+## Troubleshooting
+
+### Package not found after adding to global-packages.txt
+
+Rebuild the container:
+
+- **VS Code:** `Cmd+Shift+P` → "Dev Containers: Rebuild Container"
+
+### pnpm vs npm conflict
+
+Choose one and stick with it. Delete the other's lock file.
+
+### Node version mismatch
+
+Check `.nvmrc` or `package.json` engines field matches container Node version.
+
+### Want to use different Node version?
+
+Update `devcontainer.patch.json`:
+
+```json
+{
+    "features": {
+        "ghcr.io/devcontainers/features/node:1": {
+            "version": "18" // or "20", "21", etc.
+        }
+    }
+}
+```
+
+## Related Overlays
+
+- **postgres** - PostgreSQL for Node.js apps
+- **redis** - Session storage, caching
+- **playwright** - E2E testing
+- **codex** - Alternative with pnpm + .codex mount

package/overlays/nodejs/devcontainer.patch.json

@@ -0,0 +1,49 @@
+{
+    "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
+    "features": {
+        "./features/cross-distro-packages": {
+            "apt": "build-essential",
+            "apk": "build-base"
+        },
+        "ghcr.io/devcontainers/features/node:1": {
+            "version": "lts",
+            "nodeGypDependencies": true,
+            "installYarnUsingApt": true
+        }
+    },
+    "customizations": {
+        "vscode": {
+            "extensions": [
+                "dbaeumer.vscode-eslint",
+                "esbenp.prettier-vscode",
+                "christian-kohler.npm-intellisense"
+            ],
+            "settings": {
+                "editor.defaultFormatter": "esbenp.prettier-vscode",
+                "editor.codeActionsOnSave": {
+                    "source.fixAll.eslint": "explicit"
+                },
+                "[typescript]": {
+                    "editor.defaultFormatter": "esbenp.prettier-vscode"
+                },
+                "[javascript]": {
+                    "editor.defaultFormatter": "esbenp.prettier-vscode"
+                }
+            }
+        }
+    },
+    "remoteEnv": {
+        "PATH": "${containerEnv:HOME}/.local/share/pnpm:${containerEnv:HOME}/.npm-global/bin:${containerEnv:PATH}"
+    },
+    "forwardPorts": [3000, 8080],
+    "portsAttributes": {
+        "3000": {
+            "label": "Dev Server",
+            "onAutoForward": "openBrowser"
+        },
+        "8080": {
+            "label": "Web App",
+            "onAutoForward": "notify"
+        }
+    }
+}

package/overlays/nodejs/global-packages.txt

@@ -0,0 +1,16 @@
+# Node.js Global Packages
+# Customize this file to add or remove globally installed npm packages
+# Format: one package per line, with optional version
+# Example: typescript@5.3.0
+
+# pnpm - Fast, disk space efficient package manager
+pnpm
+
+# Add your custom global packages here
+# Common examples:
+# typescript
+# ts-node
+# nodemon
+# pm2
+# eslint
+# prettier

package/overlays/nodejs/overlay.yml

@@ -0,0 +1,14 @@
+id: nodejs
+name: Node.js
+description: Node.js LTS with TypeScript and tooling
+category: language
+supports: []
+requires: []
+suggests: []
+conflicts: []
+tags:
+    - language
+    - nodejs
+    - javascript
+    - typescript
+ports: []

package/overlays/nodejs/setup.sh

@@ -0,0 +1,46 @@
+#!/bin/bash
+# Node.js setup script - Install global npm packages
+
+set -e
+
+# Extract overlay name from script filename (setup-<overlay>.sh -> <overlay>)
+OVERLAY_NAME=$(basename "$0" | sed 's/setup-//;s/\.sh$//')
+
+echo "📦 Installing Node.js global packages..."
+
+# Read packages from configuration file if it exists
+if [ -f ".devcontainer/global-packages-${OVERLAY_NAME}.txt" ]; then
+    echo "📦 Installing packages from global-packages-${OVERLAY_NAME}.txt..."
+    
+    packages=()
+    while IFS= read -r line || [ -n "$line" ]; do
+        # Skip comments and empty lines
+        [[ "$line" =~ ^#.*$ ]] && continue
+        [[ -z "$line" ]] && continue
+        
+        packages+=("$line")
+    done < ".devcontainer/global-packages-${OVERLAY_NAME}.txt"
+    
+    if [ ${#packages[@]} -gt 0 ]; then
+        echo "  Installing: ${packages[*]}"
+        npm install -g "${packages[@]}"
+    fi
+else
+    # Fallback to pnpm only
+    echo "📦 Installing pnpm (default)..."
+    npm install -g pnpm
+fi
+
+# Verify pnpm installation (if included)
+if command -v pnpm &> /dev/null; then
+    echo "✓ pnpm installed successfully: $(pnpm --version)"
+fi
+
+# Install project dependencies if package.json exists
+if [ -f "package.json" ]; then
+    echo "📦 Installing project dependencies..."
+    npm install || true
+    echo "✓ Project dependencies installed"
+fi
+
+echo "✓ Node.js setup complete"

package/overlays/nodejs/verify.sh

@@ -0,0 +1,32 @@
+#!/bin/bash
+# Verification script for Node.js overlay
+# Confirms Node.js and npm are installed
+
+set -e
+
+echo "🔍 Verifying Node.js overlay..."
+echo ""
+
+# Check node is installed
+echo "1️⃣ Checking Node.js..."
+if command -v node &> /dev/null; then
+    node --version
+    echo "   ✅ Node.js found"
+else
+    echo "   ❌ Node.js not found"
+    exit 1
+fi
+
+# Check npm is installed
+echo ""
+echo "2️⃣ Checking npm..."
+if command -v npm &> /dev/null; then
+    npm --version
+    echo "   ✅ npm found"
+else
+    echo "   ❌ npm not found"
+    exit 1
+fi
+
+echo ""
+echo "✅ Node.js overlay verification complete"

package/overlays/otel-collector/.env.example

@@ -0,0 +1,9 @@
+# OpenTelemetry Collector version
+OTEL_COLLECTOR_VERSION=latest
+
+# OpenTelemetry Collector ports
+OTEL_GRPC_PORT=4317
+OTEL_HTTP_PORT=4318
+OTEL_METRICS_PORT=8888
+OTEL_EXPORTER_PORT=8889
+OTEL_HEALTH_PORT=13133