container-superposition 0.1.1

package/features/cross-distro-packages/README.md

@@ -0,0 +1,146 @@
+# Cross-Distribution Package Manager
+
+A devcontainer feature that installs system packages with automatic distribution detection, supporting both apt (Debian/Ubuntu) and apk (Alpine Linux) package managers.
+
+## Features
+
+- 🔍 **Auto-detection**: Automatically detects whether the container uses apt or apk
+- 📦 **Distro-specific packages**: Specify different package names for each distribution
+- 🧹 **Clean installation**: Cleans up package manager caches to minimize image size
+- ⚡ **Fast**: No unnecessary updates or cache rebuilds
+
+## Usage
+
+### Basic Example
+
+```json
+{
+    "features": {
+        "./features/cross-distro-packages": {
+            "apt": "build-essential python3-dev",
+            "apk": "build-base python3-dev"
+        }
+    }
+}
+```
+
+### Real-World Examples
+
+**Node.js Build Tools:**
+
+```json
+{
+    "features": {
+        "./features/cross-distro-packages": {
+            "apt": "build-essential",
+            "apk": "build-base"
+        }
+    }
+}
+```
+
+**Python Development:**
+
+```json
+{
+    "features": {
+        "./features/cross-distro-packages": {
+            "apt": "build-essential python3-dev",
+            "apk": "build-base python3-dev"
+        }
+    }
+}
+```
+
+**Redis CLI Tools:**
+
+```json
+{
+    "features": {
+        "./features/cross-distro-packages": {
+            "apt": "redis-tools",
+            "apk": "redis"
+        }
+    }
+}
+```
+
+**.NET Dependencies:**
+
+```json
+{
+    "features": {
+        "./features/cross-distro-packages": {
+            "apt": "xdg-utils pass sshpass build-essential netcat-traditional iputils-ping dnsutils git-lfs sqlite3",
+            "apk": "xdg-utils pass sshpass build-base netcat-openbsd iputils bind-tools git-lfs sqlite"
+        }
+    }
+}
+```
+
+## Options
+
+| Option | Type   | Default | Description                                                                   |
+| ------ | ------ | ------- | ----------------------------------------------------------------------------- |
+| `apt`  | string | `""`    | Space-separated list of packages for apt-based distributions (Debian, Ubuntu) |
+| `apk`  | string | `""`    | Space-separated list of packages for apk-based distributions (Alpine Linux)   |
+
+## Package Name Differences
+
+Common packages that have different names across distributions:
+
+| Debian/Ubuntu (apt)  | Alpine (apk)     | Purpose                       |
+| -------------------- | ---------------- | ----------------------------- |
+| `build-essential`    | `build-base`     | C/C++ compiler toolchain      |
+| `dnsutils`           | `bind-tools`     | DNS utilities (dig, nslookup) |
+| `netcat-traditional` | `netcat-openbsd` | Network utility               |
+| `sqlite3`            | `sqlite`         | SQLite database               |
+| `redis-tools`        | `redis`          | Redis CLI tools               |
+
+## How It Works
+
+1. Checks for `apk` command (Alpine Linux)
+2. Falls back to `apt-get` (Debian/Ubuntu)
+3. **Deduplicates** the package list (if multiple overlays specify the same packages)
+4. Installs the appropriate package list
+5. Cleans up package manager caches
+
+## Multiple Overlays
+
+When using multiple overlays that reference this feature, packages are **automatically deduplicated** at two levels:
+
+1. **Composer-level merge**: The composition engine merges all cross-distro-packages declarations before writing devcontainer.json
+2. **Runtime deduplication**: The install script also deduplicates packages as a safety measure
+
+**Example:**
+
+```json
+// nodejs overlay adds:
+"./features/cross-distro-packages": {
+  "apt": "build-essential"
+}
+
+// python overlay adds:
+"./features/cross-distro-packages": {
+  "apt": "build-essential python3-dev"
+}
+
+// Final devcontainer.json (after composition):
+"./features/cross-distro-packages": {
+  "apt": "build-essential python3-dev",  // deduplicated!
+  "apk": "build-base python3-dev"
+}
+```
+
+You don't need to worry about conflicts when combining overlays - the system handles it automatically.
+
+## Notes
+
+- Runs as root during container build
+- Uses `--no-install-recommends` (apt) and `--no-cache` (apk) to minimize image size
+- Automatically runs `apt-get update` before installing (apt only)
+- Cleans up `/var/lib/apt/lists/*` after installation (apt only)
+
+## Contributing
+
+To add support for additional package managers (e.g., yum, dnf, pacman), update the detection logic in `install.sh`.

package/features/cross-distro-packages/devcontainer-feature.json

@@ -0,0 +1,20 @@
+{
+    "id": "cross-distro-packages",
+    "version": "1.0.0",
+    "name": "Cross-Distribution Package Manager",
+    "description": "Install system packages with automatic distribution detection (supports apt and apk)",
+    "documentationURL": "https://github.com/veggerby/container-superposition/tree/main/features/cross-distro-packages",
+    "options": {
+        "apt": {
+            "type": "string",
+            "default": "",
+            "description": "Space-separated list of packages for apt-based distros (Debian, Ubuntu)"
+        },
+        "apk": {
+            "type": "string",
+            "default": "",
+            "description": "Space-separated list of packages for apk-based distros (Alpine)"
+        }
+    },
+    "installsAfter": ["ghcr.io/devcontainers/features/common-utils"]
+}

package/features/cross-distro-packages/install.sh

@@ -0,0 +1,58 @@
+#!/bin/bash
+# Cross-distribution package installer
+# Automatically detects package manager (apt vs apk) and installs appropriate packages
+
+set -e
+
+APT_PACKAGES="${APT:-}"
+APK_PACKAGES="${APK:-}"
+
+# Function to deduplicate space-separated package list
+deduplicate_packages() {
+    local packages="$1"
+    # Convert to array, sort, remove duplicates, join back
+    echo "$packages" | tr ' ' '\n' | sort -u | tr '\n' ' ' | sed 's/ $//'
+}
+
+# Exit early if no packages specified
+if [ -z "$APT_PACKAGES" ] && [ -z "$APK_PACKAGES" ]; then
+    echo "⚠️  No packages specified for installation"
+    exit 0
+fi
+
+echo "📦 Installing cross-distro packages..."
+
+# Detect package manager and install
+if command -v apk > /dev/null 2>&1; then
+    # Alpine Linux (apk)
+    if [ -n "$APK_PACKAGES" ]; then
+        # Deduplicate package list
+        APK_PACKAGES=$(deduplicate_packages "$APK_PACKAGES")
+        
+        echo "  Detected: Alpine Linux (apk)"
+        echo "  Installing: $APK_PACKAGES"
+        apk add --no-cache $APK_PACKAGES
+        echo "✓ Packages installed via apk"
+    else
+        echo "⚠️  No apk packages specified, skipping"
+    fi
+elif command -v apt-get > /dev/null 2>&1; then
+    # Debian/Ubuntu (apt)
+    if [ -n "$APT_PACKAGES" ]; then
+        # Deduplicate package list
+        APT_PACKAGES=$(deduplicate_packages "$APT_PACKAGES")
+        
+        echo "  Detected: Debian/Ubuntu (apt)"
+        echo "  Installing: $APT_PACKAGES"
+        apt-get update
+        DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends $APT_PACKAGES
+        apt-get clean
+        rm -rf /var/lib/apt/lists/*
+        echo "✓ Packages installed via apt"
+    else
+        echo "⚠️  No apt packages specified, skipping"
+    fi
+else
+    echo "❌ Unsupported package manager (neither apk nor apt-get found)"
+    exit 1
+fi

package/features/local-secrets-manager/devcontainer-feature.json

@@ -0,0 +1,18 @@
+{
+    "id": "local-secrets-manager",
+    "version": "1.0.0",
+    "name": "Local Secrets Manager",
+    "description": "Safe local development secrets management (never committed)",
+    "options": {
+        "autoLoadEnv": {
+            "type": "boolean",
+            "default": true,
+            "description": "Automatically load .env.local files"
+        },
+        "validateSecrets": {
+            "type": "boolean",
+            "default": true,
+            "description": "Validate required secrets are present"
+        }
+    }
+}

package/features/local-secrets-manager/install.sh

@@ -0,0 +1,127 @@
+#!/bin/bash
+set -e
+
+AUTO_LOAD_ENV=${AUTOLOADENV:-"true"}
+VALIDATE_SECRETS=${VALIDATESECRETS:-"true"}
+
+echo "Installing local secrets manager..."
+
+# Create secrets manager script
+cat > /usr/local/bin/init-secrets << 'EOF'
+#!/bin/bash
+set -e
+
+PROJECT_DIR="${1:-.}"
+
+cd "$PROJECT_DIR"
+
+echo "Initializing local secrets management..."
+
+# Create .env.example template
+cat > .env.example << 'ENVEXAMPLE'
+# Database
+DATABASE_URL=postgresql://user:password@localhost:5432/mydb
+
+# API Keys (DO NOT commit actual values)
+API_KEY=your_api_key_here
+SECRET_KEY=your_secret_key_here
+
+# External Services
+REDIS_URL=redis://localhost:6379
+SMTP_HOST=localhost
+SMTP_PORT=1025
+
+# Application
+NODE_ENV=development
+PORT=3000
+LOG_LEVEL=debug
+ENVEXAMPLE
+
+# Create .env.local (gitignored)
+if [ ! -f .env.local ]; then
+    cp .env.example .env.local
+    echo "✅ Created .env.local from template"
+else
+    echo "⚠️  .env.local already exists, skipping"
+fi
+
+# Ensure .gitignore includes secrets files
+if [ -f .gitignore ]; then
+    if ! grep -q ".env.local" .gitignore; then
+        echo "" >> .gitignore
+        echo "# Local development secrets" >> .gitignore
+        echo ".env.local" >> .gitignore
+        echo ".env.*.local" >> .gitignore
+        echo "secrets/" >> .gitignore
+    fi
+else
+    cat > .gitignore << 'GITIGNORE'
+# Local development secrets
+.env.local
+.env.*.local
+secrets/
+
+# Dependencies
+node_modules/
+GITIGNORE
+fi
+
+# Create scripts directory before writing validation script
+mkdir -p scripts
+
+# Create secrets validation script
+cat > scripts/validate-secrets.sh << 'VALIDATE'
+#!/bin/bash
+set -e
+
+if [ ! -f .env.local ]; then
+    echo "❌ .env.local not found!"
+    echo "Run 'init-secrets' to create it from .env.example"
+    exit 1
+fi
+
+# Check for placeholder values
+if grep -q "your_.*_here" .env.local; then
+    echo "⚠️  Warning: .env.local contains placeholder values"
+    echo "Update the following before running:"
+    grep "your_.*_here" .env.local
+    exit 1
+fi
+
+echo "✅ Secrets validation passed"
+VALIDATE
+
+chmod +x scripts/validate-secrets.sh
+
+echo "✅ Local secrets management initialized!"
+echo ""
+echo "Next steps:"
+echo "1. Edit .env.local with your actual secrets"
+echo "2. Run 'scripts/validate-secrets.sh' to check configuration"
+echo "3. Never commit .env.local to git!"
+EOF
+
+chmod +x /usr/local/bin/init-secrets
+
+# Add environment loader to bashrc
+cat >> /etc/bash.bashrc << 'BASHRC'
+
+# Auto-load .env.local if present
+# Detect workspace path (supports both /workspace and /workspaces/<repo>)
+if [ -n "$VSCODE_WORKSPACE_FOLDER" ]; then
+    WORKSPACE_PATH="$VSCODE_WORKSPACE_FOLDER"
+elif [ -d "/workspaces" ]; then
+    WORKSPACE_PATH=$(find /workspaces -mindepth 1 -maxdepth 1 -type d | head -n 1)
+elif [ -d "/workspace" ]; then
+    WORKSPACE_PATH="/workspace"
+fi
+
+if [ -n "$WORKSPACE_PATH" ] && [ -f "$WORKSPACE_PATH/.env.local" ]; then
+    set -a
+    source "$WORKSPACE_PATH/.env.local"
+    set +a
+fi
+BASHRC
+
+echo "✅ Local secrets manager installed!"
+echo "Run 'init-secrets' in your project directory"

package/features/project-scaffolder/devcontainer-feature.json

@@ -0,0 +1,24 @@
+{
+    "id": "project-scaffolder",
+    "version": "1.0.0",
+    "name": "Project Scaffolder",
+    "description": "Interactive project scaffolding for common frameworks and patterns",
+    "options": {
+        "template": {
+            "type": "string",
+            "enum": ["express-typescript", "nestjs-api", "nextjs-app", "react-vite", "none"],
+            "default": "none",
+            "description": "Project template to scaffold"
+        },
+        "includeTests": {
+            "type": "boolean",
+            "default": true,
+            "description": "Include test setup (Vitest/Jest)"
+        },
+        "includeCi": {
+            "type": "boolean",
+            "default": true,
+            "description": "Include GitHub Actions CI/CD"
+        }
+    }
+}

package/features/project-scaffolder/install.sh

@@ -0,0 +1,100 @@
+#!/bin/bash
+set -e
+
+TEMPLATE=${TEMPLATE:-"none"}
+INCLUDE_TESTS=${INCLUDETESTS:-"true"}
+INCLUDE_CI=${INCLUDECI:-"true"}
+
+echo "Installing project scaffolder..."
+
+# Create scaffolder script directory
+mkdir -p /usr/local/bin/scaffolder
+
+# Install scaffolder CLI
+cat > /usr/local/bin/scaffold-project << 'EOF'
+#!/bin/bash
+set -e
+
+TEMPLATE="$1"
+PROJECT_DIR="${2:-.}"
+
+scaffold_express_typescript() {
+    echo "Scaffolding Express + TypeScript API..."
+    cat > "$PROJECT_DIR/package.json" << 'PACKAGE'
+{
+  "name": "express-api",
+  "version": "1.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "tsx watch src/index.ts",
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "test": "vitest"
+  },
+  "dependencies": {
+    "express": "^4.18.2"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/node": "^20.10.0",
+    "tsx": "^4.7.0",
+    "typescript": "^5.3.3",
+    "vitest": "^1.0.4"
+  }
+}
+PACKAGE
+
+    mkdir -p "$PROJECT_DIR/src"
+    cat > "$PROJECT_DIR/src/index.ts" << 'INDEX'
+import express from 'express';
+
+const app = express();
+const port = process.env.PORT || 3000;
+
+app.use(express.json());
+
+app.get('/health', (req, res) => {
+  res.json({ status: 'ok' });
+});
+
+app.listen(port, () => {
+  console.log(`Server running on port ${port}`);
+});
+INDEX
+
+    cat > "$PROJECT_DIR/tsconfig.json" << 'TSCONFIG'
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "node",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules"]
+}
+TSCONFIG
+
+    echo "✅ Express + TypeScript scaffolded successfully!"
+}
+
+case "$TEMPLATE" in
+    express-typescript)
+        scaffold_express_typescript
+        ;;
+    *)
+        echo "Available templates: express-typescript, nestjs-api, nextjs-app, react-vite"
+        echo "Usage: scaffold-project <template> [project-dir]"
+        ;;
+esac
+EOF
+
+chmod +x /usr/local/bin/scaffold-project
+
+echo "✅ Project scaffolder installed!"
+echo "Run 'scaffold-project <template>' to create a new project"

package/features/team-conventions/devcontainer-feature.json

@@ -0,0 +1,24 @@
+{
+    "id": "team-conventions",
+    "version": "1.0.0",
+    "name": "Team Conventions",
+    "description": "Shared code quality and style enforcement for teams",
+    "options": {
+        "preset": {
+            "type": "string",
+            "enum": ["airbnb", "standard", "google", "custom"],
+            "default": "airbnb",
+            "description": "Linting/formatting preset"
+        },
+        "enableCommitLint": {
+            "type": "boolean",
+            "default": true,
+            "description": "Enable commit message linting"
+        },
+        "enablePreCommit": {
+            "type": "boolean",
+            "default": true,
+            "description": "Enable pre-commit hooks"
+        }
+    }
+}

package/features/team-conventions/install.sh

@@ -0,0 +1,93 @@
+#!/bin/bash
+set -e
+
+PRESET=${PRESET:-"airbnb"}
+ENABLE_COMMIT_LINT=${ENABLECOMMITLINT:-"true"}
+ENABLE_PRE_COMMIT=${ENABLEPRECOMMIT:-"true"}
+
+echo "Installing team conventions (preset: $PRESET)..."
+
+# Create conventions setup script
+cat > /usr/local/bin/setup-team-conventions << 'EOF'
+#!/bin/bash
+set -e
+
+PROJECT_DIR="${1:-.}"
+PRESET="${2:-airbnb}"
+
+cd "$PROJECT_DIR"
+
+echo "Setting up team conventions with $PRESET preset..."
+
+# Create .eslintrc.json
+cat > .eslintrc.json << 'ESLINT'
+{
+  "extends": ["eslint:recommended"],
+  "env": {
+    "node": true,
+    "es2022": true
+  },
+  "parserOptions": {
+    "ecmaVersion": 2022,
+    "sourceType": "module"
+  },
+  "rules": {
+    "no-console": "warn",
+    "no-unused-vars": ["error", { "argsIgnorePattern": "^_" }],
+    "semi": ["error", "always"],
+    "quotes": ["error", "single"]
+  }
+}
+ESLINT
+
+# Create .prettierrc.json
+cat > .prettierrc.json << 'PRETTIER'
+{
+  "semi": true,
+  "trailingComma": "all",
+  "singleQuote": true,
+  "printWidth": 100,
+  "tabWidth": 2,
+  "arrowParens": "always"
+}
+PRETTIER
+
+# Create .editorconfig
+cat > .editorconfig << 'EDITORCONFIG'
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.md]
+trim_trailing_whitespace = false
+EDITORCONFIG
+
+# Create commitlint config
+cat > commitlint.config.js << 'COMMITLINT'
+module.exports = {
+  extends: ['@commitlint/config-conventional'],
+  rules: {
+    'type-enum': [
+      2,
+      'always',
+      ['feat', 'fix', 'docs', 'style', 'refactor', 'test', 'chore', 'revert']
+    ],
+    'subject-case': [2, 'never', ['upper-case']]
+  }
+};
+COMMITLINT
+
+echo "✅ Team conventions configured!"
+echo "Remember to run: npm install --save-dev eslint prettier @commitlint/cli @commitlint/config-conventional"
+EOF
+
+chmod +x /usr/local/bin/setup-team-conventions
+
+echo "✅ Team conventions installer ready!"
+echo "Run 'setup-team-conventions' in your project directory"

package/overlays/.registry/README.md

@@ -0,0 +1,14 @@
+# Registry Files
+
+This directory contains special metadata files that don't fit into individual overlay manifests.
+
+## Files
+
+- **base-images.yml** - Available base container images (Debian, Alpine, Ubuntu, etc.)
+- **base-templates.yml** - Base devcontainer templates (plain, compose)
+
+These files are loaded during initialization to provide choices for base images and templates.
+
+## Note
+
+Preset definitions are stored in `overlays/presets/*.yml`.

package/overlays/.registry/base-images.yml

@@ -0,0 +1,26 @@
+base_images:
+    - id: bookworm
+      name: Debian Bookworm (Recommended)
+      description: Stable, battle-tested base with broad compatibility
+      image: mcr.microsoft.com/devcontainers/base:bookworm
+      package_manager: apt
+    - id: trixie
+      name: Debian Trixie
+      description: Newer packages, testing stability
+      image: mcr.microsoft.com/devcontainers/base:trixie
+      package_manager: apt
+    - id: alpine
+      name: Alpine Linux
+      description: Minimal footprint (~5MB), apk package manager
+      image: mcr.microsoft.com/devcontainers/base:alpine
+      package_manager: apk
+    - id: ubuntu
+      name: Ubuntu LTS
+      description: Popular, familiar, extensive package ecosystem
+      image: mcr.microsoft.com/devcontainers/base:ubuntu
+      package_manager: apt
+    - id: custom
+      name: Custom Image
+      description: Specify your own (may conflict with overlays)
+      image: null
+      package_manager: apt

package/overlays/.registry/base-templates.yml

@@ -0,0 +1,7 @@
+base_templates:
+    - id: plain
+      name: Plain (Image-based)
+      description: Minimal Debian image for simple projects
+    - id: compose
+      name: Compose (Multi-service)
+      description: Docker Compose infrastructure for complex applications