container-superposition 0.1.1

package/overlays/bun/README.md

@@ -0,0 +1,312 @@
+# Bun Overlay
+
+Adds Bun runtime - an all-in-one JavaScript runtime, bundler, test runner, and package manager that's faster than Node.js.
+
+## Features
+
+- **Bun** - Latest version of the Bun runtime
+- **Built-in bundler** - Fast bundling without webpack/vite
+- **Built-in test runner** - Jest-compatible testing
+- **Built-in package manager** - npm-compatible, faster installs
+- **TypeScript support** - Native TypeScript execution
+- **Node.js compatibility** - Runs most Node.js packages
+- **VS Code Extensions:**
+    - Bun for Visual Studio Code (oven.bun-vscode)
+    - ESLint (dbaeumer.vscode-eslint)
+    - Prettier (esbenp.prettier-vscode)
+
+## How It Works
+
+This overlay installs Bun via the official installation script. Bun is a drop-in replacement for Node.js with significantly faster startup times and module resolution. It includes Node.js LTS for compatibility with packages that require native Node.js APIs.
+
+**Installation method:**
+
+- Bun via official install script
+- Node.js LTS for compatibility
+- Installed to ~/.bun
+
+## Common Commands
+
+### Package Management
+
+```bash
+# Install dependencies (npm-compatible)
+bun install
+
+# Add package
+bun add express
+
+# Add dev dependency
+bun add -d typescript
+
+# Remove package
+bun remove express
+
+# Update all dependencies
+bun update
+
+# Global install
+bun add -g typescript
+```
+
+### Running Scripts
+
+```bash
+# Run TypeScript/JavaScript directly
+bun run index.ts
+bun run server.js
+
+# Run package.json script
+bun run dev
+bun run build
+bun run test
+
+# Run with watch mode
+bun --watch run index.ts
+```
+
+### Building and Bundling
+
+```bash
+# Bundle application
+bun build ./index.tsx --outdir ./dist
+
+# Bundle with minification
+bun build ./index.tsx --minify --outdir ./dist
+
+# Bundle for production
+bun build ./index.tsx --minify --sourcemap --outdir ./dist
+
+# Create standalone executable
+bun build ./cli.ts --compile --outfile mycli
+```
+
+### Testing
+
+```bash
+# Run tests (Jest-compatible)
+bun test
+
+# Run specific test file
+bun test file.test.ts
+
+# Watch mode
+bun test --watch
+
+# Coverage
+bun test --coverage
+```
+
+### HTTP Server
+
+```bash
+# Create simple server (built-in)
+bun run server.ts
+
+# Example server.ts:
+cat > server.ts << 'EOF'
+const server = Bun.serve({
+  port: 3000,
+  fetch(request) {
+    return new Response("Hello from Bun!");
+  },
+});
+
+console.log(`Listening on http://localhost:${server.port}`);
+EOF
+
+bun run server.ts
+```
+
+## Use Cases
+
+- **Modern web applications** - React, Vue, Svelte with faster builds
+- **API servers** - High-performance REST/GraphQL APIs
+- **CLI tools** - Fast command-line applications
+- **Microservices** - Lightweight services with fast cold starts
+- **Edge functions** - Serverless functions with quick startup
+- **Full-stack apps** - Next.js, Remix with Bun runtime
+
+**Integrates well with:**
+
+- `postgres`, `redis`, `mysql` - Database drivers (pg, ioredis, mysql2)
+- `docker-sock` - Docker SDK (dockerode)
+- `prometheus` - Metrics collection (prom-client)
+
+## Configuration
+
+### bunfig.toml
+
+Create `bunfig.toml` in project root:
+
+```toml
+[install]
+# Configure package manager
+production = false
+optional = true
+dev = true
+
+# Registry
+registry = "https://registry.npmjs.org"
+
+[test]
+# Test configuration
+coverage = true
+```
+
+### tsconfig.json
+
+Bun works with standard TypeScript configuration:
+
+```json
+{
+    "compilerOptions": {
+        "target": "ES2022",
+        "module": "ESNext",
+        "moduleResolution": "bundler",
+        "types": ["bun-types"]
+    }
+}
+```
+
+## Application Integration
+
+### Web Server with Bun
+
+```typescript
+// server.ts
+const server = Bun.serve({
+    port: 3000,
+    fetch(req) {
+        const url = new URL(req.url);
+
+        if (url.pathname === '/') {
+            return new Response('Hello from Bun!');
+        }
+
+        if (url.pathname === '/json') {
+            return Response.json({ message: 'JSON response' });
+        }
+
+        return new Response('Not Found', { status: 404 });
+    },
+});
+
+console.log(`Server running on http://localhost:${server.port}`);
+```
+
+**Run:**
+
+```bash
+bun run server.ts
+# Access at http://localhost:3000
+```
+
+### React with Bun
+
+```bash
+# Create React app
+bun create react myapp
+cd myapp
+
+# Install dependencies
+bun install
+
+# Run dev server
+bun run dev
+```
+
+### PostgreSQL with Bun
+
+```typescript
+import postgres from 'postgres';
+
+const sql = postgres('postgres://postgres:postgres@postgres/mydb');
+
+const users = await sql`SELECT * FROM users`;
+console.log(users);
+```
+
+## Performance Comparison
+
+| Operation           | Bun  | Node.js | Speedup   |
+| ------------------- | ---- | ------- | --------- |
+| **Package install** | 5s   | 25s     | 5x faster |
+| **Cold start**      | 50ms | 200ms   | 4x faster |
+| **Bundling**        | 2s   | 10s     | 5x faster |
+| **Test execution**  | 1s   | 5s      | 5x faster |
+
+_Approximate benchmarks for typical projects_
+
+## Troubleshooting
+
+### Issue: Package compatibility
+
+**Symptoms:**
+
+- Package doesn't work with Bun
+- Native module errors
+
+**Solution:**
+
+```bash
+# Use Node.js for specific commands
+node script.js
+
+# Or install with npm
+npm install problematic-package
+```
+
+### Issue: TypeScript types
+
+**Symptoms:**
+
+- Missing type definitions for Bun APIs
+
+**Solution:**
+
+```bash
+# Install Bun types
+bun add -d bun-types
+
+# Add to tsconfig.json
+{
+  "compilerOptions": {
+    "types": ["bun-types"]
+  }
+}
+```
+
+### Issue: Bun not in PATH
+
+**Solution:**
+
+```bash
+# Add to shell profile
+export BUN_INSTALL="$HOME/.bun"
+export PATH="$BUN_INSTALL/bin:$PATH"
+
+# Reload shell
+source ~/.bashrc
+```
+
+## References
+
+- [Official Bun Documentation](https://bun.sh/docs) - Complete Bun documentation
+- [Bun API Reference](https://bun.sh/docs/api) - Built-in APIs
+- [Bun vs Node.js](https://bun.sh/docs/runtime/nodejs-apis) - Compatibility guide
+- [Bun Examples](https://github.com/oven-sh/bun/tree/main/examples) - Sample projects
+
+**Related Overlays:**
+
+- `postgres` - PostgreSQL with pg driver
+- `redis` - Redis with ioredis
+- `docker-sock` - Docker access
+- `prometheus` - Metrics with prom-client
+
+## Notes
+
+- **Node.js Compatibility:** Bun aims for Node.js compatibility but some packages may not work
+- **Native Modules:** Some native Node.js modules may require Node.js runtime
+- **Ecosystem Maturity:** Bun is newer than Node.js; some tools may have limited support
+- **Production Use:** Evaluate thoroughly before production deployment

package/overlays/bun/devcontainer.patch.json

@@ -0,0 +1,41 @@
+{
+    "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
+    "features": {
+        "./features/cross-distro-packages": {
+            "apt": "unzip curl",
+            "apk": "unzip curl"
+        },
+        "ghcr.io/devcontainers/features/node:1": {
+            "version": "lts",
+            "nodeGypDependencies": false
+        }
+    },
+    "customizations": {
+        "vscode": {
+            "extensions": ["oven.bun-vscode", "dbaeumer.vscode-eslint", "esbenp.prettier-vscode"],
+            "settings": {
+                "editor.defaultFormatter": "esbenp.prettier-vscode",
+                "[typescript]": {
+                    "editor.defaultFormatter": "esbenp.prettier-vscode"
+                },
+                "[javascript]": {
+                    "editor.defaultFormatter": "esbenp.prettier-vscode"
+                }
+            }
+        }
+    },
+    "remoteEnv": {
+        "PATH": "${containerEnv:HOME}/.bun/bin:${containerEnv:PATH}"
+    },
+    "forwardPorts": [3000, 8080],
+    "portsAttributes": {
+        "3000": {
+            "label": "Dev Server",
+            "onAutoForward": "openBrowser"
+        },
+        "8080": {
+            "label": "Web App",
+            "onAutoForward": "notify"
+        }
+    }
+}

package/overlays/bun/overlay.yml

@@ -0,0 +1,16 @@
+id: bun
+name: Bun
+description: Bun runtime - faster JavaScript runtime and package manager
+category: language
+supports: []
+requires: []
+suggests: []
+conflicts: []
+tags:
+    - language
+    - bun
+    - javascript
+    - typescript
+ports:
+    - 3000
+    - 8080

package/overlays/bun/setup.sh

@@ -0,0 +1,79 @@
+#!/bin/bash
+# Bun setup script - Install Bun runtime
+
+set -e
+
+echo "🔧 Setting up Bun development environment..."
+
+# Install Bun with version pinning for security
+echo "📦 Installing Bun..."
+if ! command -v bun &> /dev/null; then
+    # Pin to a specific version for security and reproducibility
+    BUN_VERSION="1.1.38"
+    
+    # Detect architecture
+    ARCH=$(uname -m)
+    case $ARCH in
+        x86_64)
+            BUN_ARCH="x64"
+            # SHA256 checksum for bun-linux-x64 v1.1.38
+            BUN_CHECKSUM="a61da5357e28d4977fccd4851fed62ff4da3ea33853005c7dd93dac80bc53932"
+            ;;
+        aarch64|arm64)
+            BUN_ARCH="aarch64"
+            # SHA256 checksum for bun-linux-aarch64 v1.1.38
+            BUN_CHECKSUM="3b08fd0b31f745509e1fed9c690c80d1a32ef2b3c8d059583f643f696639bd21"
+            ;;
+        *)
+            echo "   ❌ Unsupported architecture: $ARCH"
+            echo "   Bun supports x86_64 and aarch64/arm64. Your architecture is not supported."
+            exit 1
+            ;;
+    esac
+    
+    BUN_URL="https://github.com/oven-sh/bun/releases/download/bun-v${BUN_VERSION}/bun-linux-${BUN_ARCH}.zip"
+    
+    echo "   Downloading Bun version ${BUN_VERSION} for ${ARCH}..."
+    if ! wget "${BUN_URL}" -O /tmp/bun.zip 2>&1; then
+        echo "   ❌ Failed to download Bun from ${BUN_URL}"
+        exit 1
+    fi
+    
+    # Verify checksum
+    echo "   Verifying checksum..."
+    echo "${BUN_CHECKSUM}  /tmp/bun.zip" | sha256sum -c - || {
+        echo "   ❌ Checksum verification failed!"
+        rm -f /tmp/bun.zip
+        exit 1
+    }
+    
+    # Extract and install
+    unzip -q /tmp/bun.zip -d /tmp/
+    mkdir -p "$HOME/.bun/bin"
+    mv /tmp/bun-linux-${BUN_ARCH}/bun "$HOME/.bun/bin/"
+    rm -rf /tmp/bun.zip /tmp/bun-linux-${BUN_ARCH}
+    echo "   ✅ Bun installed (${BUN_VERSION})"
+else
+    echo "   ✅ Bun already installed"
+fi
+
+# Reload shell environment
+export BUN_INSTALL="$HOME/.bun"
+export PATH="$BUN_INSTALL/bin:$PATH"
+
+# Verify installation
+if command -v bun &> /dev/null; then
+    INSTALLED_VERSION=$(bun --version)
+    echo "✓ Bun verified: v$INSTALLED_VERSION"
+else
+    echo "❌ Bun installation failed - bun command not found"
+    exit 1
+fi
+
+# Install project dependencies if package.json exists
+if [ -f "package.json" ]; then
+    echo "📦 Installing project dependencies with Bun..."
+    bun install || echo "⚠️ bun install failed"
+fi
+
+echo "✓ Bun setup complete"

package/overlays/bun/verify.sh

@@ -0,0 +1,30 @@
+#!/bin/bash
+# Verification script for Bun overlay
+
+set -e
+
+echo "🔍 Verifying Bun overlay..."
+echo ""
+
+# Check Bun is installed
+echo "1️⃣ Checking Bun..."
+if command -v bun &> /dev/null; then
+    bun --version
+    echo "   ✅ Bun found"
+else
+    echo "   ❌ Bun not found"
+    exit 1
+fi
+
+# Check Node.js is available (for compatibility)
+echo ""
+echo "2️⃣ Checking Node.js (for compatibility)..."
+if command -v node &> /dev/null; then
+    node --version
+    echo "   ✅ Node.js found (for compatibility)"
+else
+    echo "   ⚠️ Node.js not found (optional)"
+fi
+
+echo ""
+echo "✅ Bun overlay verification complete"

package/overlays/codex/README.md

@@ -0,0 +1,128 @@
+# Codex Overlay
+
+Adds OpenAI Codex CLI with a persistent `.codex` folder for configurations.
+
+## Features
+
+- **OpenAI Codex CLI** - AI-powered code generation and assistance from the command line
+- **Codex directory** - Creates `$HOME/.codex` for persistent configurations
+
+## What is OpenAI Codex CLI?
+
+The OpenAI Codex CLI (`@openai/codex`) provides command-line access to OpenAI's Codex AI model for:
+
+- **Code generation** - Generate code from natural language descriptions
+- **Code completion** - Intelligent code suggestions
+- **Code explanation** - Understand complex code
+- **Refactoring** - Improve existing code
+
+## Configuration
+
+**Configured paths:**
+
+- `$HOME/.codex` - Configuration and tools directory (created automatically during setup)
+
+## How It Works
+
+This overlay:
+
+1. Installs OpenAI Codex CLI globally via npm (`npm install -g @openai/codex`)
+2. Creates the `$HOME/.codex` directory for persistent configurations
+
+**After setup:**
+
+- The `codex` command will be available immediately (npm global binaries are in PATH)
+- Use it for AI-powered coding assistance
+
+## Verification
+
+After setup, run the verification script to ensure proper installation:
+
+```bash
+bash .devcontainer/verify-codex.sh
+```
+
+This will check:
+
+- Codex CLI is installed and in PATH
+- `.codex` directory exists
+
+## Troubleshooting
+
+### codex command not found
+
+**Issue:** After installing codex overlay, `codex` command is not recognized.
+
+**Solution:**
+
+1. Verify npm global binaries are in PATH:
+
+    ```bash
+    npm config get prefix
+    # Should show: /usr/local or similar
+
+    which codex
+    # Should show: /usr/local/bin/codex or similar
+    ```
+
+2. If not found, rebuild the devcontainer:
+    - VS Code: `Cmd+Shift+P` → "Dev Containers: Rebuild Container"
+
+3. Check installation manually:
+
+    ```bash
+    npm list -g @openai/codex
+    # Should show installed version
+    ```
+
+## Usage
+
+### Basic Commands
+
+```bash
+# Generate code from natural language
+codex "create a function that fetches user data from an API"
+
+# Get code explanations
+codex explain "what does this regex do: /^[a-zA-Z0-9]+$/"
+
+# Code completion (provide partial code)
+codex complete "function fibonacci(n) {"
+```
+
+For full documentation, visit: [OpenAI Codex CLI Documentation](https://github.com/openai/openai-codex-cli)
+
+## Optional: Persistent .codex Mount
+
+To share your `.codex` configurations between your host and container, create the directory on your host:
+
+```bash
+mkdir -p ~/.codex
+```
+
+Then add this mount to your `devcontainer.json`:
+
+```json
+"mounts": [
+  "source=${localEnv:HOME}${localEnv:USERPROFILE}/.codex,target=${containerEnv:HOME}/.codex,type=bind,consistency=cached"
+]
+```
+
+This allows you to:
+
+- Share Codex configurations across multiple devcontainers
+- Persist configurations on your host machine
+- Maintain consistent settings across projects
+
+**Important**: Only add this mount after creating the `~/.codex` directory on your host. Otherwise, the container may fail to start.
+
+## Related Overlays
+
+- **nodejs** - Required for npm and running the Codex CLI
+- **git-helpers** - Git integration for AI-generated code
+- **pre-commit** - Quality gates for AI-generated code
+
+## Additional Resources
+
+- [OpenAI Codex CLI](https://github.com/openai/openai-codex-cli)
+- [OpenAI Platform](https://platform.openai.com/)

package/overlays/codex/devcontainer.patch.json

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

package/overlays/codex/overlay.yml

@@ -0,0 +1,14 @@
+id: codex
+name: Codex
+description: OpenAI Codex CLI for AI-powered code generation and assistance
+category: dev
+supports: []
+requires:
+    - nodejs
+suggests: []
+conflicts: []
+tags:
+    - dev
+    - ai
+    - code-generation
+ports: []

package/overlays/codex/setup.sh

@@ -0,0 +1,24 @@
+#!/bin/bash
+# Codex setup script - Install OpenAI Codex CLI
+
+set -e
+
+echo "📦 Installing OpenAI Codex CLI..."
+
+# Install @openai/codex globally
+npm install -g @openai/codex
+
+# Verify codex installation
+if command -v codex &> /dev/null; then
+    echo "✓ Codex CLI installed successfully: $(codex --version 2>/dev/null || echo 'installed')"
+else
+    echo "✗ Codex CLI installation failed"
+    exit 1
+fi
+
+# Create .codex directory for configuration
+mkdir -p "$HOME/.codex"
+
+echo "✓ Codex setup complete"
+echo "ℹ️  OpenAI Codex CLI: https://github.com/openai/openai-codex-cli"
+echo "ℹ️  Configuration directory: $HOME/.codex"

package/overlays/codex/verify.sh

@@ -0,0 +1,30 @@
+#!/bin/bash
+# Codex overlay verification script
+
+set -e
+
+echo "🔍 Verifying Codex overlay setup..."
+
+# Check if codex CLI is installed
+if ! command -v codex &> /dev/null; then
+    echo "✗ codex CLI is not installed or not in PATH"
+    exit 1
+fi
+
+echo "✓ codex CLI is installed: $(codex --version 2>/dev/null || echo 'installed')"
+
+# Check .codex directory exists
+if [ -d "$HOME/.codex" ]; then
+    echo "✓ .codex directory exists: $HOME/.codex"
+else
+    echo "⚠️  .codex directory not found at $HOME/.codex"
+fi
+
+echo ""
+echo "✅ Codex overlay verification complete!"
+echo ""
+
+echo "💡 Tips:"
+echo "  - Run 'codex --help' to see available commands"
+echo "  - Your Codex home directory is: $HOME/.codex"
+echo "  - Ensure 'codex' is available on your PATH inside the devcontainer"