container-superposition 0.1.1

package/docs/quick-reference.md

@@ -0,0 +1,326 @@
+# Quick Reference
+
+## Base Images
+
+| Image                  | ID         | Use Case                              | Stability    |
+| ---------------------- | ---------- | ------------------------------------- | ------------ |
+| **Debian Bookworm** ⭐ | `bookworm` | Production-ready, recommended default | Stable (LTS) |
+| **Debian Trixie**      | `trixie`   | Newer packages for testing            | Testing      |
+| **Custom Image** ⚠️    | `custom`   | Specific requirements, may conflict   | Varies       |
+
+**Default**: Debian Bookworm (`mcr.microsoft.com/devcontainers/base:bookworm`)
+
+- Battle-tested in production
+- Broad compatibility with all overlays
+- Regular security updates
+
+**When to use custom images**:
+
+- Specific compliance requirements
+- Organization-standardized base images
+- Need for particular base OS (Ubuntu, Alpine, etc.)
+
+⚠️ **Caution**: Custom images may require overlay configuration adjustments and thorough testing.
+
+## Base Templates
+
+| Template    | Use Case           | Contents                                             |
+| ----------- | ------------------ | ---------------------------------------------------- |
+| **plain**   | Simple projects    | Minimal Debian image, git, zsh, basic tools          |
+| **compose** | Multi-service apps | Docker Compose, devcontainer service, devnet network |
+
+## Interactive Overlay Selection
+
+When running the questionnaire interactively, overlays are presented in a **categorized multi-select with dependency tracking**:
+
+**Features**:
+
+- 📋 **Categorized view** - Overlays grouped by category with visual separators
+- ⚡ **Dependency auto-resolution** - Required dependencies automatically added
+- ⚠️ **Conflict detection** - Post-selection conflict resolution UI
+- 🔍 **Space to toggle** - Select/deselect individual overlays
+- ✓ **Visual indicators** - Required dependencies marked with `(required)` in yellow
+- 📊 **Stack compatibility** - Only shows overlays compatible with selected stack
+
+**Keyboard workflow**:
+
+- `↑/↓` - Navigate overlays
+- `Space` - Toggle selection
+- `Enter` - Confirm selection
+
+**Dependency Resolution**:
+
+- **Automatic**: Select Grafana → Prometheus auto-added (marked as required)
+- **Recursive**: Dependencies of dependencies also auto-added
+- **Post-selection**: Conflicts (e.g., docker-in-docker ↔ docker-sock) resolved after selection
+
+**Example workflow**:
+
+1. Select Node.js, PostgreSQL, Grafana
+2. System auto-adds Prometheus (required by Grafana)
+3. No conflicts → Configuration complete
+4. If conflicts exist → Resolve conflicts UI appears
+
+This ensures valid configurations without manual dependency tracking!
+
+## Language Overlays
+
+| Overlay    | Version     | Key Features                    | Extensions                                   |
+| ---------- | ----------- | ------------------------------- | -------------------------------------------- |
+| **dotnet** | .NET 10     | C# DevKit, build tools, testing | C# DevKit, GUID generator, Nuke, REST Client |
+| **nodejs** | Node LTS    | TypeScript, npm/yarn            | ESLint, Prettier, npm IntelliSense           |
+| **python** | Python 3.12 | pip, venv, dev tools            | Pylance, Black, Ruff                         |
+| **mkdocs** | Python 3.12 | MkDocs, Material theme          | Markdown All-in-One, Markdownlint, Mermaid   |
+
+## Database Overlays
+
+| Overlay      | Version | Ports | Environment Variables                         |
+| ------------ | ------- | ----- | --------------------------------------------- |
+| **postgres** | 16      | 5432  | POSTGRES_DB, POSTGRES_USER, POSTGRES_PASSWORD |
+| **redis**    | 7       | 6379  | REDIS_PASSWORD (optional)                     |
+
+## Observability Overlays
+
+| Overlay            | Purpose             | Ports                                       | Dependencies          |
+| ------------------ | ------------------- | ------------------------------------------- | --------------------- |
+| **otel-collector** | Telemetry pipeline  | 4317 (gRPC), 4318 (HTTP), 8889 (Prometheus) | -                     |
+| **jaeger**         | Distributed tracing | 16686 (UI), 14250 (model.proto)             | -                     |
+| **prometheus**     | Metrics collection  | 9090                                        | -                     |
+| **grafana**        | Visualization       | 3000                                        | prometheus (required) |
+| **loki**           | Log aggregation     | 3100                                        | -                     |
+
+### Observability Stack Combinations
+
+| Stack            | Use Case               | Command                                                         |
+| ---------------- | ---------------------- | --------------------------------------------------------------- |
+| **Traces Only**  | Distributed tracing    | `--observability jaeger`                                        |
+| **Metrics Only** | Performance monitoring | `--observability prometheus,grafana`                            |
+| **Standard**     | Traces + Metrics       | `--observability otel-collector,jaeger,prometheus,grafana`      |
+| **Complete**     | Full observability     | `--observability otel-collector,jaeger,prometheus,grafana,loki` |
+
+## Cloud/DevOps Overlays
+
+| Overlay          | Tools         | Extensions                     |
+| ---------------- | ------------- | ------------------------------ |
+| **aws-cli**      | AWS CLI       | AWS Toolkit                    |
+| **azure-cli**    | Azure CLI     | Azure Account, Azure Resources |
+| **kubectl-helm** | kubectl, Helm | Kubernetes                     |
+
+## Development Tool Overlays
+
+| Overlay              | Purpose                        | Contents                     | Conflicts        |
+| -------------------- | ------------------------------ | ---------------------------- | ---------------- |
+| **docker-in-docker** | Docker daemon inside container | Docker CLI, daemon           | docker-sock      |
+| **docker-sock**      | Docker socket mounting         | Docker CLI, socket access    | docker-in-docker |
+| **playwright**       | Browser testing                | Playwright, Chromium         | -                |
+| **codex**            | AI code assistant              | Codex tools and integrations | -                |
+
+## Service Startup Order
+
+Services start in this order (controlled by `_serviceOrder`):
+
+1. **Order 0** - Infrastructure: postgres, redis
+2. **Order 1** - Observability backends: jaeger, prometheus, loki
+3. **Order 2** - Middleware: otel-collector
+4. **Order 3** - Visualization: grafana
+5. **Last** - devcontainer (main application)
+
+## Common Commands
+
+### Interactive
+
+```bash
+npm run init
+```
+
+### Simple Scenarios
+
+```bash
+# Plain image with language
+npm run init -- --stack plain --language python
+
+# Compose with database
+npm run init -- --stack compose --language nodejs --postgres
+```
+
+### Production-Ready
+
+```bash
+# Microservice with full observability
+npm run init -- \
+  --stack compose \
+  --language dotnet \
+  --database postgres+redis \
+  --observability otel-collector,jaeger,prometheus,grafana,loki \
+  --cloud-tools kubectl-helm
+
+# Multi-cloud development
+npm run init -- \
+  --stack compose \
+  --language python \
+  --postgres \
+  --cloud-tools aws-cli,azure-cli,kubectl-helm
+```
+
+## Output Structure
+
+### Minimal (plain + language)
+
+```
+.devcontainer/
+└── devcontainer.json
+```
+
+### Typical (compose + language + database)
+
+```
+.devcontainer/
+├── devcontainer.json
+├── docker-compose.yml
+├── docker-compose.postgres.yml
+└── .env.example
+```
+
+### Full (compose + language + database + observability)
+
+```
+.devcontainer/
+├── devcontainer.json
+├── docker-compose.yml                 # Base
+├── docker-compose.postgres.yml        # Database
+├── docker-compose.otel-collector.yml  # Telemetry
+├── docker-compose.jaeger.yml          # Tracing
+├── docker-compose.prometheus.yml      # Metrics
+├── docker-compose.grafana.yml         # Visualization
+├── docker-compose.loki.yml            # Logs
+├── .env.example                       # Merged variables
+├── otel-collector-config.yaml         # Collector config
+├── prometheus.yml                     # Prometheus config
+├── grafana-datasources.yml            # Grafana datasources
+└── loki-config.yaml                   # Loki config
+```
+
+## Environment Variables by Overlay
+
+### Databases
+
+```bash
+# PostgreSQL
+POSTGRES_VERSION=16
+POSTGRES_DB=devdb
+POSTGRES_USER=postgres
+POSTGRES_PASSWORD=postgres
+POSTGRES_PORT=5432
+
+# Redis
+REDIS_VERSION=7
+REDIS_PORT=6379
+REDIS_PASSWORD=  # Optional
+```
+
+### Observability
+
+```bash
+# OpenTelemetry Collector
+OTEL_COLLECTOR_VERSION=latest
+
+# Jaeger
+JAEGER_VERSION=latest
+
+# Prometheus
+PROMETHEUS_VERSION=latest
+
+# Grafana
+GRAFANA_VERSION=latest
+GRAFANA_ADMIN_USER=admin
+GRAFANA_ADMIN_PASSWORD=admin
+
+# Loki
+LOKI_VERSION=latest
+```
+
+## Port Reference
+
+| Port  | Service     | Purpose                 |
+| ----- | ----------- | ----------------------- |
+| 3000  | Grafana     | Visualization dashboard |
+| 3100  | Loki        | Log ingestion API       |
+| 4317  | Jaeger/OTLP | OTLP gRPC receiver      |
+| 4318  | Jaeger/OTLP | OTLP HTTP receiver      |
+| 5000  | .NET        | HTTP endpoint           |
+| 5001  | .NET        | HTTPS endpoint          |
+| 5432  | PostgreSQL  | Database                |
+| 6379  | Redis       | Cache                   |
+| 8000  | MkDocs      | Documentation server    |
+| 8080  | Generic     | Web application         |
+| 8888  | OTLP        | Collector metrics       |
+| 8889  | OTLP        | Prometheus exporter     |
+| 9090  | Prometheus  | Metrics API/UI          |
+| 13133 | OTLP        | Health check            |
+| 16686 | Jaeger      | Tracing UI              |
+
+## Dependencies
+
+### Required for Observability
+
+| Component      | Depends On               |
+| -------------- | ------------------------ |
+| otel-collector | jaeger, prometheus, loki |
+| grafana        | prometheus, loki, jaeger |
+| devcontainer   | All selected services    |
+
+### Standalone Services
+
+These work independently:
+
+- postgres
+- redis
+- jaeger (can accept traces directly)
+- prometheus (can scrape directly)
+- loki (can accept logs directly)
+
+## Migration from Old Templates
+
+| Old Template      | New Equivalent                                                                                                              |
+| ----------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `dotnet`          | `--stack compose --language dotnet`                                                                                         |
+| `node-typescript` | `--stack compose --language nodejs`                                                                                         |
+| `python-mkdocs`   | `--stack plain --language mkdocs`                                                                                           |
+| `fullstack`       | `--stack compose --language nodejs --database postgres+redis --observability otel-collector,jaeger,prometheus,grafana,loki` |
+
+## File Types
+
+| File                      | Behavior                                       |
+| ------------------------- | ---------------------------------------------- |
+| `devcontainer.patch.json` | Merged into devcontainer.json (not copied)     |
+| `.env.example`            | Merged into combined .env.example (not copied) |
+| `docker-compose.yml`      | Copied as `docker-compose.{overlay}.yml`       |
+| Other files               | Copied as-is to output directory               |
+| Directories               | Copied recursively to output directory         |
+
+## Type Definitions
+
+```typescript
+// Base templates
+type Stack = 'plain' | 'compose';
+
+// Languages
+type LanguageOverlay = 'dotnet' | 'nodejs' | 'python' | 'mkdocs';
+
+// Databases
+type Database = 'none' | 'postgres' | 'redis' | 'postgres+redis';
+
+// Observability
+type ObservabilityTool = 'otel-collector' | 'jaeger' | 'prometheus' | 'grafana' | 'loki';
+
+// Cloud tools
+type CloudTool = 'azure-cli' | 'aws-cli' | 'kubectl-helm';
+```
+
+## Helpful Links
+
+- [Architecture](architecture.md) - Deep dive into composition
+- [Dependencies](dependencies.md) - Service dependency management
+- [Creating Overlays](creating-overlays.md) - Overlay development guide
+- [Examples](examples.md) - Usage examples and patterns
+- [Contributing](../../CONTRIBUTING.md) - How to contribute

package/docs/ux.md

@@ -0,0 +1,170 @@
+# User Experience
+
+The init tool provides a polished CLI experience with visual enhancements for usability and engagement.
+
+## Visual Design
+
+### Color Coding (chalk)
+
+- **Cyan** - Headers, section titles, important labels
+- **Green** - Success states, confirmations, checkmarks
+- **Yellow** - User input prompts, warnings
+- **Red** - Errors, failures
+- **White** - Primary content, values
+- **Gray/Dim** - Secondary info, hints, progress details
+
+### Bordered Boxes (boxen)
+
+Different border styles indicate different message types:
+
+- **Round borders** - General information, summaries
+- **Double borders** - Success messages, completion
+- **Thick borders** - Errors, critical messages
+
+### Progress Feedback (ora)
+
+Animated spinners show progress during:
+
+- File generation
+- Template composition
+- Overlay application
+- Any async operations
+
+### Professional CLI (commander)
+
+- Built-in `--help` documentation
+- Version information (`--version`)
+- Clear option descriptions
+- Automatic validation
+
+## Interactive Flow
+
+### Welcome Banner
+
+Cyan-bordered box with centered title and subtitle, setting professional tone.
+
+### Question Flow
+
+Each question follows this pattern:
+
+1. Bold cyan question with emoji number
+2. List of options (if applicable)
+3. Yellow prompt for input
+4. Green checkmark with confirmation
+5. Dim text showing selected value
+
+### Configuration Summary
+
+Green-bordered box showing all selections before generation:
+
+- Stack choice
+- Docker-in-Docker setting
+- Database selection
+- Playwright enabled/disabled
+- Cloud tools list
+- Output path
+
+### Progress Indicators
+
+Spinner animation with cyan text during generation, followed by dimmed progress messages for each overlay applied.
+
+### Success Message
+
+Double-bordered green box with:
+
+- Bold success headline
+- Next steps numbered list
+- Note about configuration independence
+
+### Error Handling
+
+Red-bordered box with:
+
+- Bold error headline
+- Clear error message
+- No raw stack traces
+
+## Non-Interactive Mode
+
+Same visual polish as interactive mode:
+
+- Blue box indicating non-interactive mode
+- Configuration summary box
+- Spinner during generation
+- Success/error boxes
+
+Professional help text via `--help` with clear option descriptions and examples.
+
+## Design Principles
+
+### Progressive Disclosure
+
+Show one question at a time, confirm each selection, summarize before execution.
+
+### Visual Hierarchy
+
+- Bold for headers
+- Dim for secondary info
+- Color for message types
+- Boxes for important sections
+
+### Immediate Feedback
+
+- Checkmarks confirm selections
+- Spinners show progress
+- Clear success/error states
+- No silent operations
+
+### Scannability
+
+- Emoji markers for sections
+- Consistent indentation
+- Grouped related information
+- Clear visual separation
+
+### Professional Polish
+
+- No raw errors
+- Friendly messages
+- Helpful next steps
+- Acknowledgment of independence
+
+## Libraries
+
+| Library                 | Purpose          | Usage              |
+| ----------------------- | ---------------- | ------------------ |
+| **chalk** (^5.3.0)      | Terminal styling | Colors, bold, dim  |
+| **boxen** (^7.1.1)      | Terminal boxes   | Headers, summaries |
+| **ora** (^8.0.1)        | Spinners         | Progress feedback  |
+| **commander** (^12.0.0) | CLI parsing      | Arguments, help    |
+
+## Accessibility
+
+### Terminal Compatibility
+
+Works across different terminals:
+
+- Modern terminals (full color, Unicode)
+- Basic terminals (ASCII fallbacks)
+- CI environments (no animation)
+
+### Graceful Degradation
+
+If terminal doesn't support:
+
+- Colors → plain text
+- Spinners → simple dots
+- Unicode → ASCII characters
+
+The tool remains fully functional.
+
+## Philosophy Alignment
+
+Visual enhancements maintain humble tool principles:
+
+- ✅ No lock-in - Pretty output is ephemeral
+- ✅ Stateless - Visual feedback doesn't persist
+- ✅ Optional - Non-interactive mode available
+- ✅ Simple - UX aids clarity, not complexity
+
+Beautiful interface, simple implementation.

package/features/README.md

@@ -0,0 +1,85 @@
+# Custom Features
+
+**Only** custom features that add value beyond what's available on [containers.dev](https://containers.dev/features).
+
+## Philosophy
+
+We **do not** replicate existing features. Use official features from containers.dev for:
+
+- Git, Docker-in-Docker, common utilities
+- Language runtimes (Node, Python, Go, etc.)
+- Cloud CLIs (AWS, Azure, GCP)
+- Common development tools
+
+This directory contains **unique** features that solve specific problems not addressed by official features.
+
+## Available Custom Features
+
+### cross-distro-packages
+
+**NEW**: Cross-distribution package manager with automatic distro detection.
+
+- Supports apt (Debian/Ubuntu) and apk (Alpine)
+- Single feature declaration for multi-distro compatibility
+- Eliminates duplicated package installation logic
+- Clean package manager cache cleanup
+
+### project-scaffolder
+
+Interactive project initialization for common frameworks and patterns.
+
+- Express API, NestJS, Next.js scaffolding
+- Test setup with Vitest/Jest
+- CI/CD configuration templates
+- Interactive CLI prompts
+
+### team-conventions
+
+Shared code quality and style enforcement for teams.
+
+- Pre-configured ESLint, Prettier, commitlint
+- Husky pre-commit hooks
+- Team-specific linting rules
+- Consistent formatting across projects
+
+### local-secrets-manager
+
+Safe local development secrets management (never committed to git).
+
+- `.env.local` template generation
+- Secret validation and loading
+- Integration with VS Code settings
+- Prevents accidental commits of secrets
+
+## Using These Features
+
+Add to your `devcontainer.json` alongside official features:
+
+```json
+{
+    "features": {
+        "ghcr.io/devcontainers/features/node:1": { "version": "20" },
+        "ghcr.io/devcontainers/features/git:1": {},
+        "./features/project-scaffolder": { "template": "express-typescript" },
+        "./features/team-conventions": { "preset": "airbnb" }
+    }
+}
+```
+
+## Creating Custom Features
+
+Only add features here that:
+
+1. **Aren't available** on containers.dev
+2. **Solve real problems** for multiple projects
+3. **Are composable** - work with official features
+4. **Are well-tested** and documented
+
+Feature structure:
+
+```
+features/my-feature/
+├── devcontainer-feature.json  # Metadata
+├── install.sh                  # Installation script
+└── README.md                   # Documentation
+```