container-superposition 0.1.1

package/overlays/gcloud/README.md

@@ -0,0 +1,269 @@
+# Google Cloud SDK Overlay
+
+Adds Google Cloud SDK (gcloud) with comprehensive tooling for GCP development.
+
+## Features
+
+- **gcloud CLI** - Google Cloud command-line interface
+- **gsutil** - Cloud Storage management
+- **bq** - BigQuery command-line tool
+- **GKE gcloud auth plugin** - For Kubernetes cluster authentication
+- **VS Code Extension:** Cloud Code (googlecloudtools.cloudcode)
+
+## Authentication
+
+### Interactive Login (Development)
+
+```bash
+# Login with browser-based OAuth
+gcloud auth login
+
+# Set default project
+gcloud config set project YOUR_PROJECT_ID
+
+# Verify authentication
+gcloud auth list
+```
+
+### Service Account (CI/CD)
+
+```bash
+# Using service account JSON key
+gcloud auth activate-service-account \
+  --key-file=/path/to/service-account-key.json
+
+# Or via environment variable
+export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account-key.json
+gcloud auth activate-service-account \
+  --key-file="${GOOGLE_APPLICATION_CREDENTIALS}"
+```
+
+### Application Default Credentials (ADC)
+
+For applications using Google Cloud client libraries:
+
+```bash
+# Set ADC for development
+gcloud auth application-default login
+
+# Verify ADC is configured
+gcloud auth application-default print-access-token
+```
+
+**Environment variable approach:**
+
+```bash
+export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account-key.json
+```
+
+## Common Commands
+
+### Project Management
+
+```bash
+# List projects
+gcloud projects list
+
+# Set active project
+gcloud config set project PROJECT_ID
+
+# Get current project
+gcloud config get-value project
+```
+
+### Compute Engine
+
+```bash
+# List VM instances
+gcloud compute instances list
+
+# SSH into instance
+gcloud compute ssh INSTANCE_NAME
+
+# Create instance
+gcloud compute instances create my-instance \
+  --zone=us-central1-a \
+  --machine-type=e2-medium
+```
+
+### Cloud Storage (gsutil)
+
+```bash
+# List buckets
+gsutil ls
+
+# Create bucket
+gsutil mb gs://my-bucket-name
+
+# Copy files
+gsutil cp file.txt gs://my-bucket/
+gsutil cp gs://my-bucket/file.txt ./
+
+# Sync directory
+gsutil rsync -r ./local-dir gs://my-bucket/remote-dir
+```
+
+### GKE (Google Kubernetes Engine)
+
+```bash
+# List clusters
+gcloud container clusters list
+
+# Get cluster credentials
+gcloud container clusters get-credentials CLUSTER_NAME \
+  --zone=us-central1-a
+
+# Verify kubectl context
+kubectl config current-context
+```
+
+### BigQuery (bq)
+
+```bash
+# List datasets
+bq ls
+
+# Query data
+bq query --use_legacy_sql=false \
+  'SELECT * FROM `project.dataset.table` LIMIT 10'
+
+# Load data
+bq load dataset.table data.csv schema.json
+```
+
+### Cloud Functions
+
+```bash
+# List functions
+gcloud functions list
+
+# Deploy function
+gcloud functions deploy my-function \
+  --runtime=nodejs20 \
+  --trigger-http \
+  --allow-unauthenticated
+```
+
+## Configuration
+
+### Set Defaults
+
+```bash
+# Set default region
+gcloud config set compute/region us-central1
+
+# Set default zone
+gcloud config set compute/zone us-central1-a
+
+# View all config
+gcloud config list
+```
+
+### Multiple Configurations
+
+```bash
+# Create named configuration
+gcloud config configurations create dev
+gcloud config configurations create prod
+
+# Switch configuration
+gcloud config configurations activate dev
+
+# List configurations
+gcloud config configurations list
+```
+
+## Common Use Cases
+
+### GCP Development
+
+- Deploy Cloud Functions
+- Manage Cloud Run services
+- Interact with GCS buckets
+
+### GKE Development
+
+- Authenticate to GKE clusters
+- Deploy containerized applications
+- Manage Kubernetes resources
+
+### Data Engineering
+
+- BigQuery queries and data loading
+- Cloud Storage data pipelines
+- Dataflow job management
+
+## Best Practices
+
+1. **Use service accounts** for automation and CI/CD
+2. **Store credentials securely** - Never commit service account keys
+3. **Use ADC** for local development with client libraries
+4. **Set default project** to avoid `--project` flags
+5. **Use configurations** for multi-environment workflows
+
+## Security Considerations
+
+### Service Account Keys
+
+⚠️ **Never commit service account keys to version control**
+
+Use one of these secure methods:
+
+- **Environment variables** in `.env` (excluded from git)
+- **Secret management** (e.g., HashiCorp Vault)
+- **Cloud-based secrets** (e.g., Secret Manager)
+- **Workload Identity** (for GKE)
+
+### Least Privilege
+
+Grant minimal required permissions to service accounts:
+
+```bash
+# Example: Grant Storage Object Viewer role
+gcloud projects add-iam-policy-binding PROJECT_ID \
+  --member="serviceAccount:SA_EMAIL" \
+  --role="roles/storage.objectViewer"
+```
+
+## Troubleshooting
+
+### gcloud command not found
+
+Rebuild container:
+
+- **VS Code:** `Cmd+Shift+P` → "Dev Containers: Rebuild Container"
+
+### Authentication errors
+
+```bash
+# Clear and re-authenticate
+gcloud auth revoke
+gcloud auth login
+```
+
+### Wrong project active
+
+```bash
+# Check current project
+gcloud config get-value project
+
+# Switch project
+gcloud config set project NEW_PROJECT_ID
+```
+
+### ADC not working
+
+```bash
+# Re-establish ADC
+gcloud auth application-default login
+
+# Or set GOOGLE_APPLICATION_CREDENTIALS
+export GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json
+```
+
+## Related Overlays
+
+- **kubectl-helm** - Kubernetes management (works with GKE)
+- **terraform** - Infrastructure as Code for GCP resources
+- **pulumi** - Modern IaC with TypeScript/Python/Go
+- **nodejs/python/dotnet** - For Cloud Functions/Run development

package/overlays/gcloud/devcontainer.patch.json

@@ -0,0 +1,14 @@
+{
+    "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
+    "features": {
+        "ghcr.io/devcontainers/features/google-cloud-cli:1": {
+            "version": "latest",
+            "installGkeGcloudAuthPlugin": true
+        }
+    },
+    "customizations": {
+        "vscode": {
+            "extensions": ["googlecloudtools.cloudcode"]
+        }
+    }
+}

package/overlays/gcloud/overlay.yml

@@ -0,0 +1,14 @@
+id: gcloud
+name: Google Cloud SDK
+description: Google Cloud Platform command-line tools (gcloud, gsutil, bq)
+category: cloud
+supports: []
+requires: []
+suggests: []
+conflicts: []
+tags:
+    - cloud
+    - gcp
+    - google
+    - cli
+ports: []

package/overlays/gcloud/verify.sh

@@ -0,0 +1,52 @@
+#!/bin/bash
+# Verification script for gcloud overlay
+# Confirms Google Cloud SDK is installed
+
+set -e
+
+echo "🔍 Verifying gcloud overlay..."
+echo ""
+
+# Check gcloud is installed
+echo "1️⃣ Checking gcloud CLI..."
+if command -v gcloud &> /dev/null; then
+    gcloud version | head -1
+    echo "   ✅ gcloud CLI found"
+else
+    echo "   ❌ gcloud CLI not found"
+    exit 1
+fi
+
+# Check gsutil is installed
+echo ""
+echo "2️⃣ Checking gsutil..."
+if command -v gsutil &> /dev/null; then
+    gsutil version -l | head -1
+    echo "   ✅ gsutil found"
+else
+    echo "   ❌ gsutil not found"
+    exit 1
+fi
+
+# Check bq is installed
+echo ""
+echo "3️⃣ Checking bq (BigQuery CLI)..."
+if command -v bq &> /dev/null; then
+    bq version | head -1
+    echo "   ✅ bq found"
+else
+    echo "   ❌ bq not found"
+    exit 1
+fi
+
+# Check GKE auth plugin
+echo ""
+echo "4️⃣ Checking GKE gcloud auth plugin..."
+if command -v gke-gcloud-auth-plugin &> /dev/null; then
+    echo "   ✅ GKE auth plugin found"
+else
+    echo "   ⚠️  GKE auth plugin not found (may not be required for all use cases)"
+fi
+
+echo ""
+echo "✅ gcloud overlay verification complete"

package/overlays/git-helpers/README.md

@@ -0,0 +1,168 @@
+# Git Helpers Overlay
+
+Comprehensive Git tooling with GPG/SSH support, Git LFS, and GitHub CLI.
+
+## What's Included
+
+- **Git** - Latest version with enhanced configuration
+- **Git LFS** - Large File Storage support
+- **GitHub CLI (gh)** - GitHub command-line tool
+- **SSH Agent Forwarding** - Mounts host SSH keys (read-only)
+- **GPG Support** - Mounts host GPG keys for commit signing
+- **VS Code Extensions**:
+    - GitLens - Enhanced Git visualization
+    - GitHub Pull Requests - PR management in VS Code
+    - Git Graph - Interactive git graph visualization
+
+## Configuration
+
+### SSH Keys (Optional Mount)
+
+To use your host SSH keys in the container, add this mount to your `devcontainer.json`:
+
+```json
+"mounts": [
+  "source=${localEnv:HOME}${localEnv:USERPROFILE}/.ssh,target=/home/vscode/.ssh,type=bind,consistency=cached,readOnly=true"
+]
+```
+
+This allows you to:
+
+- Push/pull from Git repositories using SSH
+- Use SSH agent forwarding
+- Maintain existing SSH configurations
+
+**Note**: Keys are mounted read-only for security. Generate new keys inside the container if needed.
+
+### GPG Keys (Optional Mount)
+
+To use your host GPG keys in the container, add this mount to your `devcontainer.json`:
+
+```json
+"mounts": [
+  "source=${localEnv:HOME}${localEnv:USERPROFILE}/.gnupg,target=/home/vscode/.gnupg,type=bind,consistency=cached"
+]
+```
+
+**Important**: Only add this mount if you have a `~/.gnupg` directory on your host machine. Otherwise, the container may fail to start.
+
+### GPG Commit Signing
+
+GPG commit signing is supported but requires manual setup:
+
+1. Import your GPG keys into the container, or generate new ones:
+
+    ```bash
+    # Generate a new key
+    gpg --full-generate-key
+
+    # Or import from your host (copy your key ID first on host with: gpg --list-secret-keys)
+    # On host: gpg --export-secret-keys YOUR_KEY_ID > key.gpg
+    # In container: gpg --import key.gpg
+    ```
+
+2. Configure Git to use your signing key:
+
+    ```bash
+    git config --global user.signingkey YOUR_KEY_ID
+    git config --global commit.gpgsign true
+    git config --global tag.gpgsign true
+    ```
+
+**Note**: GPG keys are not automatically mounted to avoid container startup failures when `~/.gnupg` doesn't exist on the host.
+
+### GitHub CLI Authentication
+
+Authenticate with GitHub:
+
+```bash
+gh auth login
+```
+
+Follow the interactive prompts to authenticate via browser or token.
+
+## Git LFS
+
+Git LFS is pre-installed. To use it in your repository:
+
+```bash
+# Initialize in your repo
+git lfs install
+
+# Track large files (e.g., videos, datasets)
+git lfs track "*.mp4"
+git lfs track "*.zip"
+
+# Commit the .gitattributes file
+git add .gitattributes
+git commit -m "Configure Git LFS"
+```
+
+## Useful Git Aliases
+
+A sample `.gitconfig-devcontainer` is created with useful aliases:
+
+- `git st` - Status
+- `git co` - Checkout
+- `git br` - Branch
+- `git ci` - Commit
+- `git unstage` - Unstage files
+- `git last` - Show last commit
+- `git visual` - Pretty graph visualization
+- `git amend` - Amend last commit without editing message
+
+Include it in your `.gitconfig`:
+
+```ini
+[include]
+    path = ~/.gitconfig-devcontainer
+```
+
+## GitHub CLI Usage
+
+```bash
+# Create a pull request
+gh pr create
+
+# Check out a PR locally
+gh pr checkout 123
+
+# View repository issues
+gh issue list
+
+# Create a new repository
+gh repo create
+```
+
+## Troubleshooting
+
+### SSH Permissions
+
+If you encounter SSH permission errors, the setup script automatically fixes permissions:
+
+- `~/.ssh` directory: 700
+- SSH key files: 600
+
+### GPG Agent Issues
+
+If GPG signing fails, ensure the GPG agent is running:
+
+```bash
+gpg-agent --daemon
+```
+
+### Git LFS Not Tracking Files
+
+Verify LFS is initialized in your repository:
+
+```bash
+git lfs install
+git lfs ls-files  # List tracked files
+```
+
+## Security Notes
+
+- SSH keys are mounted **read-only** from your host
+- GPG keys are mounted with restricted permissions (700/600)
+- Never commit private keys to your repository
+- Use SSH agent forwarding for secure remote access

package/overlays/git-helpers/devcontainer.patch.json

@@ -0,0 +1,33 @@
+{
+    "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
+    "features": {
+        "ghcr.io/devcontainers/features/git:1": {
+            "ppa": true,
+            "version": "os-provided"
+        },
+        "ghcr.io/devcontainers/features/git-lfs:1": {
+            "version": "latest"
+        },
+        "ghcr.io/devcontainers/features/github-cli:1": {
+            "version": "latest"
+        }
+    },
+    "customizations": {
+        "vscode": {
+            "extensions": [
+                "eamodio.gitlens",
+                "github.vscode-pull-request-github",
+                "mhutchie.git-graph"
+            ],
+            "settings": {
+                "git.enableCommitSigning": false,
+                "git.enableSmartCommit": true,
+                "git.confirmSync": false,
+                "git.autofetch": true
+            }
+        }
+    },
+    "postStartCommand": {
+        "enable-git-safe-directory": "git config --global --add safe.directory ${containerWorkspaceFolder}"
+    }
+}

package/overlays/git-helpers/overlay.yml

@@ -0,0 +1,15 @@
+id: git-helpers
+name: Git Helpers
+description: Git LFS, GitHub CLI, GPG/SSH support for secure Git operations
+category: dev
+supports: []
+requires: []
+suggests: []
+conflicts: []
+tags:
+    - dev
+    - git
+    - security
+    - ssh
+    - gpg
+ports: []

package/overlays/git-helpers/setup.sh

@@ -0,0 +1,91 @@
+#!/bin/bash
+# Git helpers setup script
+
+set -e
+
+echo "🔧 Setting up Git helpers..."
+
+# Verify Git installation
+if command -v git &> /dev/null; then
+    echo "✓ Git installed: $(git --version)"
+else
+    echo "✗ Git not found"
+    exit 1
+fi
+
+# Verify Git LFS installation
+if command -v git-lfs &> /dev/null; then
+    echo "✓ Git LFS installed: $(git-lfs version)"
+    # Initialize Git LFS for the user
+    git lfs install --skip-repo
+else
+    echo "✗ Git LFS not found"
+    exit 1
+fi
+
+# Verify GitHub CLI installation
+if command -v gh &> /dev/null; then
+    echo "✓ GitHub CLI installed: $(gh --version | head -n 1)"
+else
+    echo "✗ GitHub CLI not found"
+    exit 1
+fi
+
+# Set up SSH permissions if .ssh directory exists
+if [ -d "$HOME/.ssh" ]; then
+    chmod 700 "$HOME/.ssh"
+    chmod 600 "$HOME/.ssh"/* 2>/dev/null || true
+    echo "✓ SSH directory permissions configured"
+fi
+
+# Set up GPG permissions if .gnupg directory exists
+if [ -d "$HOME/.gnupg" ]; then
+    chmod 700 "$HOME/.gnupg"
+    chmod 600 "$HOME/.gnupg"/* 2>/dev/null || true
+    echo "✓ GPG directory permissions configured"
+fi
+
+# Create sample .gitconfig-include if it doesn't exist
+if [ ! -f "$HOME/.gitconfig-devcontainer" ]; then
+    cat > "$HOME/.gitconfig-devcontainer" << 'EOF'
+# Git configuration for devcontainer
+# Include this in your .gitconfig with:
+# [include]
+#     path = ~/.gitconfig-devcontainer
+
+[core]
+    autocrlf = input
+    filemode = false
+
+[push]
+    default = current
+    autoSetupRemote = true
+
+[pull]
+    rebase = true
+
+[rebase]
+    autoStash = true
+
+# Useful aliases
+[alias]
+    st = status
+    co = checkout
+    br = branch
+    ci = commit
+    unstage = reset HEAD --
+    last = log -1 HEAD
+    visual = log --graph --oneline --all --decorate
+    amend = commit --amend --no-edit
+EOF
+    echo "✓ Sample .gitconfig-devcontainer created"
+fi
+
+echo "✓ Git helpers setup complete"
+echo ""
+echo "💡 Tips:"
+echo "  - SSH keys are mounted from your host ~/.ssh directory (read-only)"
+echo "  - GPG keys are mounted from your host ~/.gnupg directory"
+echo "  - To enable commit signing, set git.enableCommitSigning in VS Code settings"
+echo "  - Authenticate with GitHub CLI: gh auth login"
+echo "  - Initialize Git LFS in your repo: git lfs install"