container-superposition 0.1.3 → 0.1.5

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/gemini-cli/README.md

@@ -0,0 +1,77 @@
+# Gemini CLI Overlay
+
+Adds the Google Gemini CLI (`gemini`) for AI-powered development assistance directly in the terminal.
+
+## Features
+
+- **Gemini CLI** — Google's AI-powered coding assistant for the terminal
+- **Gemini 2.0 Flash** — Free tier available with Google account
+
+## What is Gemini CLI?
+
+The Google Gemini CLI is an open-source AI agent that brings Google's Gemini models directly to your terminal workflow:
+
+- **Code generation** — Generate code from natural language descriptions
+- **Codebase queries** — Ask questions about your code
+- **Agentic tasks** — Execute multi-step coding tasks autonomously
+- **Web grounding** — Access Google Search for up-to-date information
+
+## How It Works
+
+This overlay installs `@google/gemini-cli` globally via npm, making the `gemini` command available in your devcontainer.
+
+## Common Commands
+
+```bash
+# Start an interactive session
+gemini
+
+# Ask a one-off question
+gemini "how do I implement a binary search tree in TypeScript?"
+
+# Check version
+gemini --version
+```
+
+## Use Cases
+
+- **Code generation** — Describe features, Gemini implements them
+- **Codebase exploration** — Understand large or unfamiliar codebases
+- **Debugging** — Diagnose and fix errors with AI help
+- **Spec-Driven Development** — Works with `spec-kit` overlay via `specify init --ai gemini`
+
+**Integrates well with:**
+
+- `spec-kit` — Use Gemini CLI with the SDD workflow
+- `nodejs` — Required for installation
+- `git-helpers` — Git integration for AI-generated code
+
+## Configuration
+
+Authenticate using your Google account or a Gemini API key:
+
+```bash
+# Interactive authentication (opens browser)
+gemini auth
+
+# Or set API key
+export GEMINI_API_KEY=your-api-key
+```
+
+## Verification
+
+```bash
+bash .devcontainer/scripts/verify-gemini-cli.sh
+```
+
+## References
+
+- [Gemini CLI GitHub](https://github.com/google-gemini/gemini-cli)
+- [Google AI Studio](https://aistudio.google.com/)
+
+**Related Overlays:**
+
+- `spec-kit` — Spec-Driven Development with Gemini 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/gemini-cli/devcontainer.patch.json

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

package/overlays/gemini-cli/overlay.yml

@@ -0,0 +1,15 @@
+id: gemini-cli
+name: Gemini CLI
+description: Google Gemini CLI for AI-powered development assistance
+category: dev
+supports: []
+requires:
+    - nodejs
+suggests: []
+conflicts: []
+tags:
+    - dev
+    - ai
+    - gemini
+    - google
+ports: []

package/overlays/gemini-cli/setup.sh

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

package/overlays/gemini-cli/verify.sh

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

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"

package/overlays/grpc-tools/verify.sh

@@ -0,0 +1,47 @@
+#!/bin/bash
+# Verification script for gRPC Tools overlay
+# Confirms protoc, buf, and grpcurl are installed
+
+set -e
+
+echo "🔍 Verifying gRPC Tools overlay..."
+echo ""
+
+ALL_CHECKS_PASSED=true
+
+# Check protoc
+echo "1️⃣ Checking protoc (Protocol Buffers compiler)..."
+if command -v protoc &> /dev/null; then
+    echo "   ✅ protoc found: $(protoc --version)"
+else
+    echo "   ❌ protoc not found"
+    ALL_CHECKS_PASSED=false
+fi
+
+# Check buf
+echo ""
+echo "2️⃣ Checking buf CLI..."
+if command -v buf &> /dev/null; then
+    echo "   ✅ buf found: $(buf --version)"
+else
+    echo "   ❌ buf not found"
+    ALL_CHECKS_PASSED=false
+fi
+
+# Check grpcurl
+echo ""
+echo "3️⃣ Checking grpcurl..."
+if command -v grpcurl &> /dev/null; then
+    echo "   ✅ grpcurl found: $(grpcurl --version 2>&1 | head -1)"
+else
+    echo "   ❌ grpcurl not found"
+    ALL_CHECKS_PASSED=false
+fi
+
+echo ""
+if [ "$ALL_CHECKS_PASSED" = true ]; then
+    echo "✅ gRPC Tools overlay verification complete"
+else
+    echo "❌ Some gRPC tools are missing"
+    exit 1
+fi

package/overlays/keycloak/.env.example

@@ -0,0 +1,5 @@
+# Keycloak Configuration
+KEYCLOAK_VERSION=26.0
+KEYCLOAK_PORT=8180
+KEYCLOAK_ADMIN=admin
+KEYCLOAK_ADMIN_PASSWORD=admin