container-superposition 0.1.1

package/overlays/just/README.md

@@ -0,0 +1,443 @@
+# Just Task Runner Overlay
+
+Simple, fast, and powerful task runner using `just` (Rust-based).
+
+## What's Included
+
+- **just** - Command runner (v1.25.2)
+- **Sample Justfile** - Ready-to-use task definitions
+- **Shell completion** - Tab completion for bash/zsh
+- **Common tasks** - Build, test, lint, dev server patterns
+
+## Why Just?
+
+- **Simple syntax** - Easier than Makefiles
+- **Fast** - Rust-based, minimal overhead
+- **Cross-platform** - Works on Linux, macOS, Windows
+- **No dependencies** - Single binary
+- **Great UX** - Clear errors, helpful messages
+- **Popular** - 18k+ GitHub stars, widely adopted
+
+## Quick Start
+
+List available tasks:
+
+```bash
+just --list
+# or simply
+just
+```
+
+Run a task:
+
+```bash
+just build
+just test
+just dev
+```
+
+## Justfile Syntax
+
+### Basic Task
+
+```just
+# Simple task
+hello:
+    echo "Hello, world!"
+```
+
+### Task with Arguments
+
+```just
+# Task with parameters
+greet name:
+    echo "Hello, {{name}}!"
+
+# Usage: just greet "Alice"
+```
+
+### Task Dependencies
+
+```just
+# Task that depends on others
+deploy: build test
+    ./deploy.sh
+```
+
+### Variables
+
+```just
+# Set variables
+version := "1.0.0"
+
+show-version:
+    echo "Version: {{version}}"
+```
+
+### Conditional Execution
+
+```just
+# Run only if condition is true
+test:
+    #!/usr/bin/env bash
+    if [ -f package.json ]; then
+        npm test
+    fi
+```
+
+### Environment Variables
+
+```just
+# Export environment variable
+export DATABASE_URL := "postgres://localhost/db"
+
+migrate:
+    ./migrate.sh
+```
+
+## Sample Justfile Tasks
+
+The generated Justfile includes:
+
+### Development Tasks
+
+- `install` - Install dependencies
+- `build` - Build the project
+- `dev` - Start development server
+- `serve` - Start production server
+- `clean` - Remove build artifacts
+
+### Quality Tasks
+
+- `test` - Run tests
+- `test-watch` - Run tests in watch mode
+- `lint` - Run linter
+- `lint-fix` - Fix linting issues
+- `format` - Format code
+- `check` - Run all checks (lint + test + build)
+
+### Git Tasks
+
+- `git-status` - Show git status
+- `git-log` - Show recent commits
+
+### Docker Tasks
+
+- `docker-up` - Start containers
+- `docker-down` - Stop containers
+- `docker-logs` - View logs
+
+### Database Tasks
+
+- `db-migrate` - Run migrations
+- `db-seed` - Seed database
+- `db-reset` - Reset database
+
+## Advanced Features
+
+### Private Tasks
+
+Prefix with underscore:
+
+```just
+# Won't show in --list
+_internal:
+    echo "Internal task"
+
+public: _internal
+    echo "Public task"
+```
+
+### Default Recipe
+
+```just
+# Runs when you type `just`
+default:
+    @just --list
+```
+
+### Recipe Parameters with Defaults
+
+```just
+# Parameter with default value
+deploy env="staging":
+    ./deploy.sh {{env}}
+
+# Usage:
+# just deploy           -> uses "staging"
+# just deploy prod      -> uses "prod"
+```
+
+### Multi-line Commands
+
+```just
+complex:
+    #!/usr/bin/env bash
+    set -euxo pipefail
+    echo "Starting complex task"
+    for i in {1..5}; do
+        echo "Step $i"
+    done
+```
+
+### Command Evaluation
+
+```just
+# Backticks execute commands
+now := `date +%Y-%m-%d`
+
+backup:
+    cp data.db "data-{{now}}.db"
+```
+
+### Conditional Recipes
+
+```just
+# Different behavior per OS
+install-deps:
+    #!/usr/bin/env bash
+    if [[ "$OSTYPE" == "linux-gnu"* ]]; then
+        apt-get install -y nodejs
+    elif [[ "$OSTYPE" == "darwin"* ]]; then
+        brew install node
+    fi
+```
+
+### .env File Support
+
+```just
+# Load .env file
+set dotenv-load
+
+# Now all .env variables are available
+show-db:
+    echo $DATABASE_URL
+```
+
+## Common Patterns
+
+### Node.js Project
+
+```just
+install:
+    npm install
+
+dev:
+    npm run dev
+
+build:
+    npm run build
+
+test:
+    npm test
+
+lint:
+    npm run lint
+
+format:
+    npm run format
+```
+
+### Python Project
+
+```just
+install:
+    pip install -r requirements.txt
+
+test:
+    pytest
+
+lint:
+    pylint src/
+
+format:
+    black src/
+
+run:
+    python -m src.main
+```
+
+### Docker Project
+
+```just
+build:
+    docker build -t myapp .
+
+run:
+    docker run -p 8080:8080 myapp
+
+up:
+    docker-compose up -d
+
+down:
+    docker-compose down
+
+logs:
+    docker-compose logs -f
+```
+
+## Tips and Tricks
+
+### Suppress Command Echo
+
+Use `@` prefix:
+
+```just
+# Shows command and output
+loud:
+    echo "I'm loud!"
+
+# Shows only output
+quiet:
+    @echo "I'm quiet!"
+```
+
+### Ignore Errors
+
+Use `-` prefix:
+
+```just
+# Continue even if command fails
+cleanup:
+    -rm -rf temp/
+    -docker stop container || true
+```
+
+### List Recipes
+
+```bash
+just --list        # List all recipes
+just --list --unsorted  # List in file order
+just --show <recipe>    # Show recipe definition
+```
+
+### Dry Run
+
+```bash
+just --dry-run build   # Show what would run
+```
+
+### Working Directory
+
+```bash
+just --working-directory /path/to/dir build
+```
+
+### Choose Recipe Interactively
+
+```bash
+just --choose   # Interactive selection
+```
+
+## Customization
+
+### Set Options
+
+```just
+# Set shell
+set shell := ["bash", "-c"]
+
+# Set working directory
+set working-directory := "./src"
+
+# Enable .env loading
+set dotenv-load
+```
+
+### Aliases
+
+```just
+alias b := build
+alias t := test
+alias d := dev
+
+# Now you can use: just b, just t, just d
+```
+
+## Debugging
+
+### Verbose Output
+
+```bash
+just --verbose build
+```
+
+### Show Recipe
+
+```bash
+just --show build
+```
+
+### Evaluate Justfile
+
+```bash
+just --evaluate
+```
+
+## Integration with Pre-commit
+
+Add to `.pre-commit-config.yaml`:
+
+```yaml
+repos:
+    - repo: local
+      hooks:
+          - id: just-lint
+            name: Run just lint
+            entry: just lint
+            language: system
+            pass_filenames: false
+```
+
+## Best Practices
+
+1. **Use @echo for user feedback** - Make tasks informative
+2. **Group related tasks** - Keep Justfile organized
+3. **Document tasks** - Add comments above recipes
+4. **Use dependencies** - Compose tasks from smaller tasks
+5. **Set default task** - Make `just` without args useful
+6. **Keep tasks simple** - Complex logic belongs in scripts
+7. **Use variables** - DRY principle
+8. **Test on clean state** - Ensure tasks work from scratch
+
+## Migration from Make
+
+| Make                 | Just                    |
+| -------------------- | ----------------------- |
+| `target: dependency` | `recipe: dependency`    |
+| `$(var)`             | `{{var}}`               |
+| `@command`           | `@command`              |
+| `.PHONY: target`     | (not needed)            |
+| `export VAR=value`   | `export VAR := "value"` |
+
+## Troubleshooting
+
+### Command Not Found
+
+Ensure just is in PATH:
+
+```bash
+which just
+# Should output: /usr/local/bin/just
+```
+
+### Justfile Syntax Error
+
+Use `just --evaluate` to check syntax.
+
+### Recipe Not Found
+
+```bash
+just --list   # Verify recipe exists
+```
+
+### Working Directory Issues
+
+Use absolute paths or `set working-directory`.
+
+## Additional Resources
+
+- [Just Documentation](https://just.systems/)
+- [Just GitHub Repository](https://github.com/casey/just)
+- [Just Examples](https://github.com/casey/just#recipes)
+- [Justfile Cheatsheet](https://cheatography.com/linux-china/cheat-sheets/justfile/)

package/overlays/just/devcontainer.patch.json

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

package/overlays/just/overlay.yml

@@ -0,0 +1,13 @@
+id: just
+name: Just Task Runner
+description: Fast, simple command runner (Rust-based alternative to Make)
+category: dev
+supports: []
+requires: []
+suggests: []
+conflicts: []
+tags:
+    - dev
+    - automation
+    - tasks
+ports: []

package/overlays/just/setup.sh

@@ -0,0 +1,182 @@
+#!/bin/bash
+# Just task runner setup script
+
+set -e
+
+echo "⚡ Setting up just task runner..."
+
+# Install just from GitHub releases
+JUST_VERSION="1.25.2"
+ARCH=$(uname -m)
+
+# SHA256 checksums for just v1.25.2
+if [ "$ARCH" = "x86_64" ]; then
+    ARCH="x86_64"
+    CHECKSUM="6804798c3744fd1ce563840ee9fe14ae53c74b3cc7b8536da3f87751d7f85501"
+elif [ "$ARCH" = "aarch64" ] || [ "$ARCH" = "arm64" ]; then
+    ARCH="aarch64"
+    CHECKSUM="f287a95846131ce8de65181b0b1ec0a0b7db4f6f8d393b3b548f70fcb5a4b0ee"
+else
+    echo "⚠️  Unsupported architecture: $ARCH"
+    ARCH="x86_64"
+    CHECKSUM="6804798c3744fd1ce563840ee9fe14ae53c74b3cc7b8536da3f87751d7f85501"
+fi
+
+echo "📦 Downloading just v${JUST_VERSION} for ${ARCH}..."
+curl -L "https://github.com/casey/just/releases/download/${JUST_VERSION}/just-${JUST_VERSION}-${ARCH}-unknown-linux-musl.tar.gz" \
+    -o /tmp/just.tar.gz
+
+# Verify checksum
+echo "🔐 Verifying checksum..."
+echo "${CHECKSUM}  /tmp/just.tar.gz" | sha256sum -c - || {
+    echo "✗ Checksum verification failed"
+    rm /tmp/just.tar.gz
+    exit 1
+}
+
+# Extract and install
+tar -xzf /tmp/just.tar.gz -C /tmp
+sudo mv /tmp/just /usr/local/bin/
+sudo chmod +x /usr/local/bin/just
+rm /tmp/just.tar.gz
+
+# Verify installation
+if command -v just &> /dev/null; then
+    echo "✓ just installed: $(just --version)"
+else
+    echo "✗ just installation failed"
+    exit 1
+fi
+
+# Create sample Justfile if it doesn't exist
+if [ ! -f Justfile ]; then
+    cat > Justfile << 'EOF'
+# Justfile - Task runner configuration
+# Run `just --list` to see all available tasks
+# Run `just <task>` to execute a task
+
+# Default task (runs when you type `just`)
+default:
+    @just --list
+
+# Install project dependencies
+install:
+    @echo "📦 Installing dependencies..."
+    npm install
+    @echo "✓ Dependencies installed"
+
+# Build the project
+build:
+    @echo "🔨 Building project..."
+    npm run build
+    @echo "✓ Build complete"
+
+# Run tests
+test:
+    @echo "🧪 Running tests..."
+    npm test
+
+# Run tests in watch mode
+test-watch:
+    @echo "👀 Running tests in watch mode..."
+    npm run test:watch
+
+# Run linter
+lint:
+    @echo "🔍 Running linter..."
+    npm run lint
+
+# Fix linting issues
+lint-fix:
+    @echo "🔧 Fixing linting issues..."
+    npm run lint -- --fix
+
+# Format code
+format:
+    @echo "💅 Formatting code..."
+    npm run format
+
+# Clean build artifacts
+clean:
+    @echo "🧹 Cleaning build artifacts..."
+    rm -rf dist/ build/ .cache/
+    @echo "✓ Clean complete"
+
+# Development server
+dev:
+    @echo "🚀 Starting development server..."
+    npm run dev
+
+# Production server
+serve:
+    @echo "🌐 Starting production server..."
+    npm start
+
+# Run all checks (lint, test, build)
+check: lint test build
+    @echo "✅ All checks passed"
+
+# Git helpers
+git-status:
+    @echo "📊 Git status:"
+    @git status
+
+git-log:
+    @echo "📜 Recent commits:"
+    @git log --oneline -10
+
+# Docker helpers
+docker-up:
+    @echo "🐳 Starting Docker containers..."
+    docker-compose up -d
+
+docker-down:
+    @echo "🛑 Stopping Docker containers..."
+    docker-compose down
+
+docker-logs:
+    @echo "📋 Docker logs:"
+    docker-compose logs -f
+
+# Database helpers (example)
+db-migrate:
+    @echo "🗄️  Running database migrations..."
+    npm run db:migrate
+
+db-seed:
+    @echo "🌱 Seeding database..."
+    npm run db:seed
+
+db-reset: db-migrate db-seed
+    @echo "✓ Database reset complete"
+
+# Help / Documentation
+help:
+    @echo "Available tasks:"
+    @just --list
+    @echo ""
+    @echo "Usage: just <task>"
+    @echo "Example: just build"
+EOF
+    echo "✓ Sample Justfile created"
+fi
+
+# Set up bash completion (if available)
+if [ -d /etc/bash_completion.d ]; then
+    just --completions bash | sudo tee /etc/bash_completion.d/just > /dev/null
+    echo "✓ Bash completion installed"
+fi
+
+# Set up zsh completion (if available)
+if [ -d /usr/local/share/zsh/site-functions ]; then
+    just --completions zsh | sudo tee /usr/local/share/zsh/site-functions/_just > /dev/null
+    echo "✓ Zsh completion installed"
+fi
+
+echo "✓ Just setup complete"
+echo ""
+echo "💡 Usage:"
+echo "  - List tasks: just --list or just"
+echo "  - Run task: just <task-name>"
+echo "  - Show task: just --show <task-name>"
+echo "  - Edit Justfile: edit your project's Justfile"