container-superposition 0.1.3 → 0.1.4

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/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:"

package/overlays/grpc-tools/README.md

@@ -0,0 +1,242 @@
+# gRPC Tools Overlay
+
+Protocol Buffers compiler, Buf schema management CLI, and grpcurl for gRPC API development.
+
+## Features
+
+- **protoc** - Protocol Buffers compiler (from system packages)
+- **buf** - Modern schema management, linting, and breaking change detection
+- **grpcurl** - Command-line tool for interacting with gRPC servers (like curl for gRPC)
+- **VS Code Extensions:**
+    - [vscode-proto3](https://marketplace.visualstudio.com/items?itemName=zxh404.vscode-proto3) - Proto3 syntax highlighting and validation
+    - [vscode-buf](https://marketplace.visualstudio.com/items?itemName=bufbuild.vscode-buf) - Buf integration for VS Code
+
+## How It Works
+
+This overlay installs the gRPC development toolchain into the dev container. `protoc` is installed via system packages, while `buf` and `grpcurl` are downloaded from their official GitHub releases.
+
+## Common Commands
+
+### protoc (Protocol Buffers Compiler)
+
+```bash
+# Compile .proto files to Go
+protoc --go_out=. --go-grpc_out=. api/v1/service.proto
+
+# Compile to Python
+protoc --python_out=. api/v1/service.proto
+
+# Compile to JavaScript/TypeScript
+protoc --js_out=import_style=commonjs,binary:. api/v1/service.proto
+
+# Check version
+protoc --version
+```
+
+### buf (Schema Management)
+
+```bash
+# Initialize buf workspace
+buf config init
+
+# Lint .proto files
+buf lint
+
+# Detect breaking changes
+buf breaking --against .git#branch=main
+
+# Generate code from .proto files
+buf generate
+
+# Format .proto files
+buf format -w
+
+# Push schema to Buf Schema Registry
+buf push
+
+# Check version
+buf --version
+```
+
+### grpcurl (gRPC Testing)
+
+```bash
+# List all services on a gRPC server
+grpcurl -plaintext localhost:50051 list
+
+# List methods on a service
+grpcurl -plaintext localhost:50051 list mypackage.MyService
+
+# Describe a method
+grpcurl -plaintext localhost:50051 describe mypackage.MyService.MyMethod
+
+# Call a method
+grpcurl -plaintext -d '{"name": "World"}' localhost:50051 mypackage.MyService/SayHello
+
+# Call with headers
+grpcurl -plaintext \
+  -H "Authorization: Bearer $TOKEN" \
+  -d '{"id": 1}' \
+  localhost:50051 mypackage.MyService/GetUser
+
+# Stream response
+grpcurl -plaintext localhost:50051 mypackage.MyService/ListUsers
+```
+
+## Example .proto File
+
+```protobuf
+syntax = "proto3";
+
+package myservice.v1;
+
+option go_package = "github.com/myorg/myservice/gen/go/myservice/v1";
+
+service UserService {
+    rpc GetUser(GetUserRequest) returns (GetUserResponse);
+    rpc ListUsers(ListUsersRequest) returns (stream User);
+    rpc CreateUser(CreateUserRequest) returns (CreateUserResponse);
+}
+
+message User {
+    string id = 1;
+    string name = 2;
+    string email = 3;
+}
+
+message GetUserRequest {
+    string id = 1;
+}
+
+message GetUserResponse {
+    User user = 1;
+}
+
+message ListUsersRequest {}
+
+message CreateUserRequest {
+    string name = 1;
+    string email = 2;
+}
+
+message CreateUserResponse {
+    User user = 1;
+}
+```
+
+## buf.yaml Configuration
+
+```yaml
+version: v2
+modules:
+    - path: proto
+lint:
+    use:
+        - DEFAULT
+breaking:
+    use:
+        - FILE
+```
+
+## buf.gen.yaml (Code Generation)
+
+```yaml
+version: v2
+plugins:
+    # Go
+    - remote: buf.build/protocolbuffers/go
+      out: gen/go
+      opt:
+          - paths=source_relative
+    - remote: buf.build/grpc/go
+      out: gen/go
+      opt:
+          - paths=source_relative
+
+    # Python
+    - remote: buf.build/protocolbuffers/python
+      out: gen/python
+
+    # TypeScript (Node.js)
+    - remote: buf.build/connectrpc/node
+      out: gen/typescript
+```
+
+## Language-Specific Setup
+
+### Go
+
+```bash
+# Install Go gRPC plugins
+go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
+go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest
+```
+
+### Node.js
+
+```bash
+# Install grpc-tools for Node.js
+npm install --save-dev grpc-tools @grpc/grpc-js @grpc/proto-loader
+```
+
+### Python
+
+```bash
+# Install Python gRPC tools
+pip install grpcio grpcio-tools
+```
+
+## Use Cases
+
+- **gRPC API development** - Design, implement, and test gRPC services
+- **Protocol Buffers schema management** - Lint, format, and version schemas
+- **gRPC endpoint testing** - Test services without a full client implementation
+- **Microservice communication** - Develop services that communicate via gRPC
+- **API documentation** - Describe and explore gRPC service contracts
+
+## Troubleshooting
+
+### protoc plugins not found
+
+After installing language-specific plugins, ensure they are in your `PATH`:
+
+```bash
+# Go plugins
+export PATH="$PATH:$(go env GOPATH)/bin"
+
+# Verify
+which protoc-gen-go
+which protoc-gen-go-grpc
+```
+
+### buf lint errors
+
+Run `buf lint` to see all lint errors:
+
+```bash
+buf lint
+# proto/api/v1/service.proto:10:1:Service name "userService" should be PascalCase
+```
+
+### grpcurl: server does not support the reflection API
+
+Enable gRPC server reflection in your service:
+
+```go
+// Go example
+import "google.golang.org/grpc/reflection"
+reflection.Register(grpcServer)
+```
+
+## References
+
+- [Protocol Buffers Documentation](https://protobuf.dev/)
+- [Buf Documentation](https://buf.build/docs/)
+- [grpcurl GitHub](https://github.com/fullstorydev/grpcurl)
+- [gRPC Documentation](https://grpc.io/docs/)
+
+**Related Overlays:**
+
+- `go` - Go language runtime
+- `nodejs` - Node.js runtime
+- `python` - Python runtime

package/overlays/grpc-tools/devcontainer.patch.json

@@ -0,0 +1,14 @@
+{
+    "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
+    "features": {
+        "./features/cross-distro-packages": {
+            "apt": "protobuf-compiler",
+            "apk": "protobuf"
+        }
+    },
+    "customizations": {
+        "vscode": {
+            "extensions": ["zxh404.vscode-proto3", "bufbuild.vscode-buf"]
+        }
+    }
+}

package/overlays/grpc-tools/overlay.yml

@@ -0,0 +1,14 @@
+id: grpc-tools
+name: gRPC Tools
+description: Protocol Buffers compiler, Buf, and grpcurl for gRPC development
+category: dev
+supports: []
+requires: []
+suggests: []
+conflicts: []
+tags:
+    - dev
+    - grpc
+    - protobuf
+    - api
+ports: []

package/overlays/grpc-tools/setup.sh

@@ -0,0 +1,57 @@
+#!/bin/bash
+# gRPC Tools setup script
+# Installs buf CLI and grpcurl
+
+set -e
+
+echo "🔧 Setting up gRPC Tools..."
+
+# Install buf CLI
+echo "📦 Installing buf CLI..."
+BUF_VERSION="${BUF_VERSION:-1.47.2}"
+
+# Detect architecture
+ARCH=$(uname -m)
+case "$ARCH" in
+    x86_64) BUF_ARCH="x86_64" ;;
+    aarch64 | arm64) BUF_ARCH="aarch64" ;;
+    *) echo "   ⚠️  Unsupported architecture: $ARCH, skipping buf installation" ; BUF_ARCH="" ;;
+esac
+
+if [ -n "$BUF_ARCH" ]; then
+    BUF_URL="https://github.com/bufbuild/buf/releases/download/v${BUF_VERSION}/buf-Linux-${BUF_ARCH}"
+    curl -sSL "$BUF_URL" -o /tmp/buf
+    sudo install -m 755 /tmp/buf /usr/local/bin/buf
+    rm -f /tmp/buf
+    echo "   ✅ buf installed: $(buf --version)"
+fi
+
+# Install grpcurl
+echo "📦 Installing grpcurl..."
+GRPCURL_VERSION="${GRPCURL_VERSION:-1.9.2}"
+
+GRPCURL_ARCH="$(uname -m)"
+case "$GRPCURL_ARCH" in
+    x86_64) GRPCURL_ARCH="x86_64" ;;
+    aarch64 | arm64) GRPCURL_ARCH="arm64" ;;
+    *) echo "   ⚠️  Unsupported architecture: $GRPCURL_ARCH, skipping grpcurl installation" ; GRPCURL_ARCH="" ;;
+esac
+
+if [ -n "$GRPCURL_ARCH" ]; then
+    GRPCURL_URL="https://github.com/fullstorydev/grpcurl/releases/download/v${GRPCURL_VERSION}/grpcurl_${GRPCURL_VERSION}_linux_${GRPCURL_ARCH}.tar.gz"
+    curl -sSL "$GRPCURL_URL" | sudo tar -xz -C /usr/local/bin grpcurl
+    echo "   ✅ grpcurl installed: $(grpcurl --version 2>&1 | head -1)"
+fi
+
+echo ""
+echo "✅ gRPC Tools setup complete"
+echo ""
+echo "💡 Quick start:"
+echo "   protoc --version          # Protocol Buffers compiler"
+echo "   buf --version             # Buf CLI (schema management)"
+echo "   grpcurl --version         # gRPC curl"
+echo ""
+echo "📚 Resources:"
+echo "   https://protobuf.dev/       # Protocol Buffers documentation"
+echo "   https://buf.build/docs/     # Buf CLI documentation"
+echo "   https://github.com/fullstorydev/grpcurl  # grpcurl documentation"