container-superposition 0.1.1

package/overlays/powershell/README.md

@@ -0,0 +1,314 @@
+# PowerShell Overlay
+
+Adds PowerShell Core (cross-platform) for scripting, automation, and cloud management tasks.
+
+## Features
+
+- **PowerShell Core** - Latest cross-platform PowerShell (pwsh)
+- **PSScriptAnalyzer** - Linting and best practice analyzer
+- **Pester** - Testing framework for PowerShell scripts
+- **PowerShellGet** - Module management
+- **VS Code Extension:** PowerShell (ms-vscode.powershell) - Complete PowerShell IDE
+- **Cross-platform** - Works on Linux, macOS, and Windows containers
+
+## How It Works
+
+This overlay installs PowerShell Core via the official devcontainers feature. PowerShell Core is the cross-platform version of PowerShell that runs on Linux, macOS, and Windows. The setup script installs essential modules for development and testing.
+
+**Installation method:**
+
+- PowerShell Core via devcontainer feature
+- Modules via PowerShellGet
+- Modules stored in user profile
+
+## Common Commands
+
+### Basic PowerShell
+
+```powershell
+# Run PowerShell
+pwsh
+
+# Run script
+pwsh ./script.ps1
+
+# Run command
+pwsh -Command "Get-Process"
+
+# Interactive mode
+pwsh -NoProfile
+```
+
+### Module Management
+
+```powershell
+# List installed modules
+Get-Module -ListAvailable
+
+# Install module
+Install-Module -Name Az -Scope CurrentUser
+
+# Import module
+Import-Module Az
+
+# Update module
+Update-Module Az
+
+# Find modules
+Find-Module -Name "*Azure*"
+
+# Uninstall module
+Uninstall-Module Az
+```
+
+### Script Development
+
+```powershell
+# Create new script
+New-Item -Path ./script.ps1 -ItemType File
+
+# Run with parameters
+pwsh ./script.ps1 -Parameter1 "value" -Parameter2 42
+
+# Run with execution policy bypass
+pwsh -ExecutionPolicy Bypass -File ./script.ps1
+
+# Measure script execution time
+Measure-Command { ./script.ps1 }
+```
+
+### Testing with Pester
+
+```powershell
+# Run all tests
+Invoke-Pester
+
+# Run specific test file
+Invoke-Pester ./Tests/MyScript.Tests.ps1
+
+# Run with coverage
+Invoke-Pester -CodeCoverage ./MyScript.ps1
+
+# Example test file (MyScript.Tests.ps1)
+Describe "MyScript Tests" {
+    It "Should return true" {
+        $result = ./MyScript.ps1
+        $result | Should -Be $true
+    }
+}
+```
+
+### Linting with PSScriptAnalyzer
+
+```powershell
+# Analyze script
+Invoke-ScriptAnalyzer -Path ./script.ps1
+
+# Analyze directory
+Invoke-ScriptAnalyzer -Path ./ -Recurse
+
+# Fix issues automatically
+Invoke-ScriptAnalyzer -Path ./script.ps1 -Fix
+
+# Check specific rules
+Invoke-ScriptAnalyzer -Path ./script.ps1 -IncludeRule PSAvoidUsingCmdletAliases
+```
+
+## Use Cases
+
+- **Cross-platform scripting** - Automation scripts that run on Linux/macOS/Windows
+- **Azure automation** - Azure resource management (Az module)
+- **AWS automation** - AWS resource management (AWS.Tools module)
+- **DevOps pipelines** - CI/CD automation scripts
+- **System administration** - Server configuration and management
+- **Windows interop** - Linux/WSL integration with Windows systems
+
+**Integrates well with:**
+
+- `azure-cli` - Azure CLI + PowerShell Az module
+- `aws-cli` - AWS CLI + PowerShell AWS.Tools
+- `kubectl-helm` - Kubernetes management scripts
+- `docker-sock` - Docker management with PowerShell
+
+## Configuration
+
+### Azure Module
+
+Install Azure PowerShell module:
+
+```powershell
+# Install Az module
+Install-Module -Name Az -Scope CurrentUser -AllowClobber
+
+# Connect to Azure
+Connect-AzAccount
+
+# List subscriptions
+Get-AzSubscription
+
+# Set subscription
+Set-AzContext -SubscriptionId "subscription-id"
+```
+
+### AWS Module
+
+Install AWS Tools for PowerShell:
+
+```powershell
+# Install AWS.Tools
+Install-Module -Name AWS.Tools.Installer -Scope CurrentUser
+
+# Install specific AWS services
+Install-AWSToolsModule AWS.Tools.EC2,AWS.Tools.S3
+
+# Configure credentials
+Set-AWSCredential -AccessKey "KEY" -SecretKey "SECRET" -StoreAs "default"
+
+# Set region
+Set-DefaultAWSRegion -Region us-east-1
+```
+
+### PowerShell Profile
+
+Create profile for startup customization:
+
+```powershell
+# Create profile
+New-Item -Path $PROFILE -ItemType File -Force
+
+# Edit profile
+code $PROFILE
+
+# Example profile content:
+# Set default editor
+$env:EDITOR = "code"
+
+# Import common modules
+Import-Module PSScriptAnalyzer
+
+# Custom aliases
+Set-Alias -Name k -Value kubectl
+```
+
+## Application Integration
+
+### Azure Resource Management
+
+```powershell
+# List all resource groups
+Get-AzResourceGroup
+
+# Create resource group
+New-AzResourceGroup -Name "MyResourceGroup" -Location "eastus"
+
+# List VMs
+Get-AzVM
+
+# Start VM
+Start-AzVM -ResourceGroupName "MyResourceGroup" -Name "MyVM"
+```
+
+### AWS S3 Operations
+
+```powershell
+# List S3 buckets
+Get-S3Bucket
+
+# Upload file
+Write-S3Object -BucketName "mybucket" -File "./file.txt" -Key "file.txt"
+
+# Download file
+Read-S3Object -BucketName "mybucket" -Key "file.txt" -File "./downloaded.txt"
+
+# List objects
+Get-S3Object -BucketName "mybucket"
+```
+
+### REST API Calls
+
+```powershell
+# GET request
+$response = Invoke-RestMethod -Uri "https://api.example.com/data" -Method Get
+
+# POST request with JSON
+$body = @{
+    name = "John"
+    age = 30
+} | ConvertTo-Json
+
+$response = Invoke-RestMethod -Uri "https://api.example.com/users" -Method Post -Body $body -ContentType "application/json"
+```
+
+## Troubleshooting
+
+### Issue: Execution policy error
+
+**Symptoms:**
+
+- "Execution policy does not allow running scripts"
+
+**Solution:**
+
+```powershell
+# Check current policy
+Get-ExecutionPolicy
+
+# Set policy for current user
+Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
+
+# Or bypass for single script
+pwsh -ExecutionPolicy Bypass -File ./script.ps1
+```
+
+### Issue: Module not found
+
+**Symptoms:**
+
+- "Module not found" error
+
+**Solution:**
+
+```powershell
+# Check module path
+$env:PSModulePath
+
+# Install module
+Install-Module -Name ModuleName -Scope CurrentUser
+
+# Import module explicitly
+Import-Module ModuleName
+```
+
+### Issue: PowerShell version mismatch
+
+**Solution:**
+
+```powershell
+# Check PowerShell version
+$PSVersionTable.PSVersion
+
+# Ensure using pwsh (PowerShell Core), not powershell (Windows PowerShell)
+which pwsh
+```
+
+## References
+
+- [PowerShell Documentation](https://docs.microsoft.com/powershell/) - Official documentation
+- [PowerShell Gallery](https://www.powershellgallery.com/) - Module repository
+- [Az PowerShell Module](https://docs.microsoft.com/powershell/azure/) - Azure management
+- [AWS Tools for PowerShell](https://aws.amazon.com/powershell/) - AWS management
+- [Pester Documentation](https://pester.dev/) - Testing framework
+- [PSScriptAnalyzer](https://github.com/PowerShell/PSScriptAnalyzer) - Code analyzer
+
+**Related Overlays:**
+
+- `azure-cli` - Azure CLI (complementary to Az module)
+- `aws-cli` - AWS CLI (complementary to AWS.Tools)
+- `kubectl-helm` - Kubernetes management
+- `docker-sock` - Docker management
+
+## Notes
+
+- **PowerShell Core vs Windows PowerShell:** This overlay installs PowerShell Core (pwsh), the cross-platform version
+- **Compatibility:** Most Windows PowerShell scripts work with PowerShell Core, but some Windows-specific features may not be available
+- **Module Scope:** Modules are installed with `-Scope CurrentUser` to avoid permission issues

package/overlays/powershell/devcontainer.patch.json

@@ -0,0 +1,22 @@
+{
+    "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
+    "features": {
+        "ghcr.io/devcontainers/features/powershell:1": {
+            "version": "latest"
+        }
+    },
+    "customizations": {
+        "vscode": {
+            "extensions": ["ms-vscode.powershell"],
+            "settings": {
+                "powershell.integratedConsole.focusConsoleOnExecute": false,
+                "[powershell]": {
+                    "editor.formatOnSave": true
+                }
+            }
+        }
+    },
+    "remoteEnv": {
+        "PSModulePath": "${containerEnv:HOME}/.local/share/powershell/Modules:${containerEnv:PSModulePath}"
+    }
+}

package/overlays/powershell/overlay.yml

@@ -0,0 +1,13 @@
+id: powershell
+name: PowerShell
+description: PowerShell Core for cross-platform scripting and automation
+category: language
+supports: []
+requires: []
+suggests: []
+conflicts: []
+tags:
+    - language
+    - powershell
+    - scripting
+ports: []

package/overlays/powershell/setup.sh

@@ -0,0 +1,29 @@
+#!/bin/bash
+# PowerShell setup script - Install common PowerShell modules
+
+set -e
+
+echo "🔧 Setting up PowerShell development environment..."
+
+# Verify PowerShell is installed
+if command -v pwsh &> /dev/null; then
+    PWSH_VERSION=$(pwsh -NoProfile -Command '$PSVersionTable.PSVersion.ToString()')
+    echo "✓ PowerShell found: v$PWSH_VERSION"
+else
+    echo "⚠️ PowerShell not found"
+    exit 1
+fi
+
+# Install common PowerShell modules
+echo "📦 Installing PowerShell modules..."
+
+# PSScriptAnalyzer (Linting and best practices)
+pwsh -NoProfile -Command 'Install-Module -Name PSScriptAnalyzer -Force -Scope CurrentUser -AllowClobber' || echo "⚠️ PSScriptAnalyzer installation failed"
+
+# Pester (Testing framework)
+pwsh -NoProfile -Command 'Install-Module -Name Pester -Force -Scope CurrentUser -AllowClobber -SkipPublisherCheck' || echo "⚠️ Pester installation failed"
+
+# PowerShellGet (Module management)
+pwsh -NoProfile -Command 'Install-Module -Name PowerShellGet -Force -Scope CurrentUser -AllowClobber' || echo "⚠️ PowerShellGet installation failed"
+
+echo "✓ PowerShell setup complete"

package/overlays/powershell/verify.sh

@@ -0,0 +1,38 @@
+#!/bin/bash
+# Verification script for PowerShell overlay
+
+set -e
+
+echo "🔍 Verifying PowerShell overlay..."
+echo ""
+
+# Check PowerShell is installed
+echo "1️⃣ Checking PowerShell..."
+if command -v pwsh &> /dev/null; then
+    pwsh -NoProfile -Command '$PSVersionTable.PSVersion'
+    echo "   ✅ PowerShell found"
+else
+    echo "   ❌ PowerShell not found"
+    exit 1
+fi
+
+# Check PSScriptAnalyzer module
+echo ""
+echo "2️⃣ Checking PSScriptAnalyzer..."
+if pwsh -NoProfile -Command 'Get-Module -ListAvailable -Name PSScriptAnalyzer' | grep -q "PSScriptAnalyzer"; then
+    echo "   ✅ PSScriptAnalyzer installed"
+else
+    echo "   ⚠️ PSScriptAnalyzer not found"
+fi
+
+# Check Pester module
+echo ""
+echo "3️⃣ Checking Pester..."
+if pwsh -NoProfile -Command 'Get-Module -ListAvailable -Name Pester' | grep -q "Pester"; then
+    echo "   ✅ Pester installed"
+else
+    echo "   ⚠️ Pester not found"
+fi
+
+echo ""
+echo "✅ PowerShell overlay verification complete"

package/overlays/pre-commit/README.md

@@ -0,0 +1,263 @@
+# Pre-commit Framework Overlay
+
+Automated code quality gates with the pre-commit framework.
+
+## What's Included
+
+- **pre-commit framework** - Git hook scripts for identifying issues
+- **Sample configuration** - Ready-to-use `.pre-commit-config.yaml`
+- **Common hooks** - Language-agnostic file checks
+- **Language-specific hooks** - Commented examples for Python, JavaScript, Shell
+
+## Quick Start
+
+The overlay automatically:
+
+1. Installs the pre-commit framework
+2. Creates a sample `.pre-commit-config.yaml` (if not present)
+3. Installs pre-commit hooks in your Git repository
+
+## Configuration
+
+### Sample Configuration
+
+A comprehensive `.pre-commit-config.yaml` is created with:
+
+**General Hooks** (enabled by default):
+
+- `trailing-whitespace` - Remove trailing whitespace
+- `end-of-file-fixer` - Ensure files end with newline
+- `check-yaml` - Validate YAML syntax
+- `check-json` - Validate JSON syntax
+- `check-toml` - Validate TOML syntax
+- `check-added-large-files` - Prevent large files (>1MB)
+- `check-case-conflict` - Prevent case-insensitive conflicts
+- `check-merge-conflict` - Detect merge conflict markers
+- `detect-private-key` - Prevent committing private keys
+- `mixed-line-ending` - Normalize line endings to LF
+- `markdownlint` - Markdown linting with auto-fix
+
+**Language-Specific Hooks** (commented out - uncomment as needed):
+
+- Python: black, isort, flake8
+- JavaScript/TypeScript: ESLint, Prettier
+- Dockerfile: hadolint
+- Shell: shellcheck
+
+### Customizing Configuration
+
+Edit `.pre-commit-config.yaml` to:
+
+- Add/remove hooks
+- Configure hook arguments
+- Update hook versions
+
+Example - Enable Python hooks:
+
+```yaml
+repos:
+    - repo: https://github.com/psf/black
+      rev: 24.2.0
+      hooks:
+          - id: black
+```
+
+## Usage
+
+### Install Hooks
+
+If not auto-installed during setup:
+
+```bash
+pre-commit install
+```
+
+### Run Manually
+
+```bash
+# Run on all files
+pre-commit run --all-files
+
+# Run on staged files only
+pre-commit run
+
+# Run specific hook
+pre-commit run trailing-whitespace
+
+# Run on specific files
+pre-commit run --files path/to/file.py
+```
+
+### Update Hooks
+
+Update hook versions to latest:
+
+```bash
+pre-commit autoupdate
+```
+
+### Skip Hooks
+
+Skip hooks for a specific commit:
+
+```bash
+git commit --no-verify
+# or
+git commit -n
+```
+
+Skip specific hook:
+
+```yaml
+# In .pre-commit-config.yaml
+- id: trailing-whitespace
+  skip: true # Temporarily skip this hook
+```
+
+## Common Hooks
+
+### File Safety Hooks
+
+- **check-added-large-files**: Prevents commits of files >1MB
+- **detect-private-key**: Scans for private keys/secrets
+- **check-case-conflict**: Prevents case-sensitivity issues
+
+### File Format Hooks
+
+- **trailing-whitespace**: Removes trailing spaces
+- **end-of-file-fixer**: Ensures newline at end of file
+- **mixed-line-ending**: Normalizes to LF (Unix style)
+
+### Syntax Validation
+
+- **check-yaml**: Validates YAML files (safe mode)
+- **check-json**: Validates JSON syntax
+- **check-toml**: Validates TOML syntax
+
+### Merge Safety
+
+- **check-merge-conflict**: Detects `<<<<<<` markers
+- **check-executables-have-shebangs**: Ensures scripts have `#!/...`
+
+## Integration with CI/CD
+
+Run pre-commit in CI pipelines:
+
+```yaml
+# GitHub Actions example
+- name: Run pre-commit
+  uses: pre-commit/action@v3.0.0
+```
+
+Or manually:
+
+```bash
+# In CI script
+pre-commit run --all-files
+```
+
+## Language-Specific Examples
+
+### Python Project
+
+Uncomment in `.pre-commit-config.yaml`:
+
+```yaml
+- repo: https://github.com/psf/black
+  rev: 24.2.0
+  hooks:
+      - id: black
+
+- repo: https://github.com/pycqa/isort
+  rev: 5.13.2
+  hooks:
+      - id: isort
+        args: [--profile, black]
+```
+
+### JavaScript/TypeScript Project
+
+Uncomment in `.pre-commit-config.yaml`:
+
+```yaml
+- repo: https://github.com/pre-commit/mirrors-prettier
+  rev: v3.1.0
+  hooks:
+      - id: prettier
+        types_or: [javascript, jsx, ts, tsx, json, yaml, markdown]
+```
+
+### Shell Scripts
+
+Uncomment in `.pre-commit-config.yaml`:
+
+```yaml
+- repo: https://github.com/shellcheck-py/shellcheck-py
+  rev: v0.9.0.6
+  hooks:
+      - id: shellcheck
+```
+
+## Troubleshooting
+
+### Hooks Not Running
+
+Ensure hooks are installed:
+
+```bash
+pre-commit install
+```
+
+### Hook Failures
+
+Run with verbose output:
+
+```bash
+pre-commit run --all-files --verbose
+```
+
+### Clearing Hook Cache
+
+Remove cached hook environments:
+
+```bash
+pre-commit clean
+pre-commit install-hooks
+```
+
+### Updating Hook Versions
+
+```bash
+pre-commit autoupdate
+```
+
+## Best Practices
+
+1. **Run before first commit**: `pre-commit run --all-files`
+2. **Update regularly**: `pre-commit autoupdate` monthly
+3. **Team consistency**: Commit `.pre-commit-config.yaml` to version control
+4. **CI validation**: Run pre-commit in CI to enforce on PRs
+5. **Skip sparingly**: Use `--no-verify` only when necessary
+
+## Performance Tips
+
+- Use `files` regex to limit hook scope
+- Enable `fail_fast: true` to stop on first failure
+- Use `stages: [commit]` to run only on commit (not push)
+
+Example:
+
+```yaml
+repos:
+    - repo: https://github.com/pre-commit/pre-commit-hooks
+      rev: v4.5.0
+      hooks:
+          - id: trailing-whitespace
+            files: \.(py|js|ts)$ # Only Python and JS files
+```
+
+## Additional Resources
+
+- [Pre-commit Documentation](https://pre-commit.com)
+- [Supported Hooks](https://pre-commit.com/hooks.html)
+- [Creating Custom Hooks](https://pre-commit.com/#new-hooks)

package/overlays/pre-commit/devcontainer.patch.json

@@ -0,0 +1,9 @@
+{
+    "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
+    "features": {
+        "ghcr.io/devcontainers/features/python:1": {
+            "version": "3.12",
+            "installTools": true
+        }
+    }
+}

package/overlays/pre-commit/overlay.yml

@@ -0,0 +1,16 @@
+id: pre-commit
+name: Pre-commit Framework
+description: Automated code quality gates with pre-commit hooks
+category: dev
+supports: []
+requires:
+    - python
+suggests:
+    - commitlint
+conflicts: []
+tags:
+    - dev
+    - git
+    - quality
+    - hooks
+ports: []