container-superposition 0.1.1

package/docs/README.md

@@ -0,0 +1,308 @@
+# Container Superposition Documentation
+
+Complete documentation for the container-superposition devcontainer scaffolding system.
+
+## 📚 Documentation Index
+
+### Getting Started
+
+- **[Publishing Guide](publishing.md)** - How to publish to npm and make the tool publicly available
+- **[Quick Reference](quick-reference.md)** - Quick lookup for templates, overlays, ports, and commands
+- **[Examples](examples.md)** - Common usage patterns and real-world scenarios
+
+### Architecture & Design
+
+- **[Architecture](architecture.md)** - Design principles, composition algorithm, and deep merge logic
+- **[Presets Architecture](presets-architecture.md)** - Meta-overlay design and preset system architecture
+- **[Dependencies](dependencies.md)** - Service dependencies, startup order, and runServices configuration
+- **[UX Design](ux.md)** - Visual design, CLI enhancements, and accessibility features
+
+### User Guides
+
+- **[Presets Guide](presets.md)** - Using stack presets for common development scenarios
+- **[Messaging Comparison](messaging-comparison.md)** - Choosing between RabbitMQ, Redpanda, and NATS
+- **[Messaging Quick Start](messaging-quick-start.md)** - Getting started with messaging overlays
+- **[Observability Workflow](observability-workflow.md)** - Setting up monitoring and tracing
+
+### Development
+
+- **[Creating Overlays](creating-overlays.md)** - Complete guide to creating new overlays
+- **[Contributing](../CONTRIBUTING.md)** - Contribution guidelines and development workflow
+- **[AGENTS.md](../AGENTS.md)** - Comprehensive guide for AI coding agents
+
+## 🎯 Quick Start
+
+### For Users
+
+```bash
+# Interactive mode (recommended)
+npx container-superposition init
+
+# Non-interactive mode
+npx container-superposition init --stack compose --language nodejs --database postgres
+```
+
+### For Contributors
+
+```bash
+# Clone and setup
+git clone https://github.com/veggerby/container-superposition.git
+cd container-superposition
+npm install
+
+# Run in development mode
+npm run init
+
+# Build and test
+npm run build
+npm test
+```
+
+## 📖 Core Concepts
+
+### Base Templates
+
+Minimal starting points for devcontainer configurations:
+
+- **plain** - Simple single-image devcontainer
+- **compose** - Docker Compose-based for multi-service setups
+
+Located in `templates/`
+
+### Overlays
+
+Composable capability modules organized by category:
+
+**Languages & Frameworks:**
+
+- dotnet, nodejs, python, mkdocs
+
+**Databases:**
+
+- postgres, redis
+
+**Observability:**
+
+- otel-collector, jaeger, prometheus, grafana, loki
+
+**Cloud Tools:**
+
+- aws-cli, azure-cli, kubectl-helm
+
+**Dev Tools:**
+
+- docker-in-docker, docker-sock, playwright, codex, git-helpers, pre-commit, commitlint, just, direnv, modern-cli-tools, ngrok
+
+Located in `overlays/`
+
+### Composition
+
+The tool uses a deep merge strategy to combine:
+
+1. Base template
+2. Selected overlays (in category order)
+3. User preferences (port offsets, custom paths)
+
+Output: Standard `.devcontainer/` folder with editable JSON/YAML files
+
+## 🔧 Architecture Overview
+
+```mermaid
+graph TD
+    A[User Input<br/>CLI/Interactive] --> B[Dependency Resolution<br/>requires/suggests]
+    B --> C[Conflict Detection<br/>conflicts field]
+    C --> D[Composition<br/>Deep Merge]
+    D --> E[Output<br/>.devcontainer/]
+```
+
+## 📁 Output Structure
+
+After running the tool:
+
+```txt
+.devcontainer/
+├── devcontainer.json              # Main configuration
+├── docker-compose.yml             # Base compose file (if using compose)
+├── .env.example                   # Environment variables
+├── superposition.json             # Generation metadata
+├── scripts/                       # Setup scripts
+│   ├── setup-*.sh                 # Overlay-specific setup
+│   └── ...
+├── verify-*.sh                    # Service verification scripts
+└── [overlay-specific files]       # Config files from overlays
+```
+
+## 🎨 Key Features
+
+### Dependency Resolution
+
+Overlays can declare relationships:
+
+```yaml
+- id: grafana
+  requires: [prometheus] # Auto-added when grafana selected
+  suggests: [loki, jaeger] # Recommended but optional
+  conflicts: [] # Cannot be used together
+```
+
+### Conflict Detection
+
+Prevents incompatible combinations:
+
+```yaml
+- id: docker-in-docker
+  conflicts: [docker-sock] # Only one Docker access method allowed
+```
+
+### Port Management
+
+Automatic port configuration with optional offset:
+
+```bash
+# Default ports
+npm run init
+
+# Add 100 to all ports (Grafana: 3000 → 3100)
+npm run init -- --port-offset 100
+```
+
+### Environment Variables
+
+Merged from all selected overlays into `.env.example`:
+
+```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=your-secure-password
+```
+
+## 🧪 Testing
+
+```bash
+# Unit tests
+npm test
+
+# Watch mode
+npm test:watch
+
+# Smoke tests (actual devcontainer generation)
+npm run test:smoke
+```
+
+## 📦 Package Structure
+
+When published to npm, includes:
+
+- ✅ Compiled JavaScript (`dist/`)
+- ✅ All templates (`templates/`)
+- ✅ All overlays (`overlays/`)
+- ✅ All features (`features/`)
+- ✅ Configuration metadata (`overlays/index.yml`)
+- ✅ Type definitions and schema (`tool/schema/`)
+- ✅ Documentation
+
+**Package size**: ~122 KB compressed, ~462 KB unpacked
+
+## 🤝 Contributing
+
+See [CONTRIBUTING.md](../CONTRIBUTING.md) for:
+
+- Development setup
+- Code style guidelines
+- Pull request process
+- Testing requirements
+
+## 📄 License
+
+MIT - See [LICENSE](../LICENSE)
+
+## 🔗 Links
+
+- **Repository**: <https://github.com/veggerby/container-superposition>
+- **Issues**: <https://github.com/veggerby/container-superposition/issues>
+- **npm Package**: <https://www.npmjs.com/package/container-superposition> (once published)
+
+## 🆘 Support
+
+- **GitHub Issues**: Bug reports and feature requests
+- **Discussions**: Questions and community support
+- **Pull Requests**: Code contributions welcome
+
+---
+
+**Philosophy**: Build a thin picker that outputs normal configurations, not a platform.
+
+- Generates once, users edit forever
+- No update or sync mechanisms
+- No state tracking
+- No proprietary formats
+
+### Stateless
+
+- Each invocation is independent
+- Output is deterministic
+- No configuration files
+
+### Optional
+
+- Templates work without the tool
+- Manual copying is always an option
+- Tool is convenience wrapper
+
+## Technology
+
+- **Node.js/TypeScript** - Cross-platform, type-safe
+- **chalk** - Terminal colors
+- **boxen** - Terminal boxes
+- **ora** - Progress spinners
+- **commander** - CLI parsing
+
+## Extension
+
+### Add an Overlay
+
+1. Create `overlays/<name>/`
+2. Add `devcontainer.patch.json`
+3. Add `overlay.yml` manifest ([schema](../tool/schema/overlay-manifest.schema.json), [detailed guide](../.github/instructions/overlay-index.instructions.md))
+4. Optional: Add `docker-compose.yml`
+5. Optional: Add `README.md` documentation
+6. Update questionnaire
+
+See [Creating Overlays Guide](creating-overlays.md) for complete instructions.
+
+### Add a Template
+
+1. Create `templates/<name>/.devcontainer/`
+2. Add complete devcontainer.json
+3. Add scripts and files
+4. Update types and questionnaire
+
+## Maintenance
+
+### Smoke Tests
+
+```bash
+npm test
+```
+
+### Build
+
+```bash
+npm run build
+```
+
+### Development
+
+```bash
+npm run init
+```
+
+Uses `tsx` for direct TypeScript execution without build step.

package/docs/architecture.md

@@ -0,0 +1,233 @@
+# Architecture
+
+The init tool is a **thin "purpose picker"** that composes devcontainer configurations from base templates and overlays.
+
+## Design Principles
+
+### Generate Once, Edit Forever
+
+The tool creates standard `.devcontainer/` folders that users own completely. There is no "sync" or "update" mechanism—once generated, the configuration is independent of the tool.
+
+### Stateless Composition
+
+No configuration tracking, version control, or state management. Each invocation is independent and produces deterministic output based on the provided options.
+
+### Plain JSON Output
+
+All output is standard `devcontainer.json` format compatible with VS Code Dev Containers and GitHub Codespaces. No proprietary schemas or custom DSLs.
+
+### Optional Tooling
+
+Templates in `templates/` work standalone. The init tool is a convenience wrapper, not a requirement.
+
+## Directory Structure
+
+```
+tool/
+├── docs/              # Architecture and design documentation
+├── overlays/          # Composable feature add-ons
+│   ├── Language/Framework
+│   │   ├── dotnet/           # .NET overlay
+│   │   ├── nodejs/           # Node.js overlay
+│   │   ├── python/           # Python overlay
+│   │   └── mkdocs/           # MkDocs overlay
+│   ├── Databases
+│   │   ├── postgres/         # PostgreSQL overlay
+│   │   └── redis/            # Redis overlay
+│   ├── Observability
+│   │   ├── otel-collector/   # OpenTelemetry Collector
+│   │   ├── jaeger/           # Distributed tracing
+│   │   ├── prometheus/       # Metrics collection
+│   │   ├── grafana/          # Visualization
+│   │   └── loki/             # Log aggregation
+│   ├── Development Tools
+│   │   ├── playwright/       # Browser automation
+│   │   ├── aws-cli/          # AWS tools
+│   │   ├── azure-cli/        # Azure tools
+│   │   └── kubectl-helm/     # Kubernetes tools
+├── questionnaire/     # Composition logic
+│   └── composer.ts    # Deep merge engine
+└── schema/            # Type definitions
+    ├── types.ts       # TypeScript interfaces
+    └── config.schema.json  # JSON schema
+
+scripts/
+├── init.ts           # CLI entry point
+├── test.sh           # Smoke tests
+└── example.js        # Programmatic usage
+```
+
+## Composition Algorithm
+
+### Input Processing
+
+1. **Parse arguments** - Commander processes CLI flags or triggers interactive questionnaire
+2. **Validate answers** - Ensure stack exists and options are compatible
+3. **Select overlays** - Based on database, playwright, cloud tools choices
+
+### Template Composition
+
+1. **Load base template** from `templates/<stack>/.devcontainer/`
+2. **Apply overlays** sequentially using deep merge
+3. **Copy template files** (scripts, etc.) from base template
+4. **Copy overlay files** (config files, docker-compose, etc.)
+5. **Merge .env.example** files from all selected overlays
+6. **Write merged configuration** to output path
+
+### Deep Merge Logic
+
+```typescript
+function deepMerge(base, overlay) {
+  for each key in overlay:
+    if key exists in base and both are objects:
+      if both are arrays:
+        concatenate and deduplicate
+      else:
+        recursively merge
+    else:
+      use overlay value
+  return merged
+}
+```
+
+Special handling:
+
+- **Arrays**: Concatenate and deduplicate (ports, packages)
+- **apt-get packages**: Merge space-separated lists
+- **Features**: Deep merge feature configs
+- **Environment variables**: Merge key-value pairs
+- **Port attributes**: Merge labeled port configurations
+
+### File Handling per Overlay
+
+Each overlay can contain multiple file types:
+
+- **devcontainer.patch.json** - Merged into devcontainer.json (not copied)
+- **.env.example** - Merged into combined .env.example (not copied separately)
+- **docker-compose.yml** - Copied as `docker-compose.{overlay}.yml`
+- **Other files/directories** - Copied as-is to output
+
+This allows overlays to provide complete configurations with config files, scripts, and directories.
+
+## Workflow
+
+```mermaid
+graph TD
+    A[User Input] --> B[CLI Parser Commander]
+    B --> C[Interactive or Non-Interactive Mode]
+    C --> D[QuestionnaireAnswers]
+    D --> E[Composer Engine]
+    E --> F[Load base template]
+    E --> G[Select overlays]
+    E --> H[Deep merge devcontainer configs]
+    E --> I[Copy template files]
+    E --> J[Copy overlay files]
+    E --> K[Merge .env.example files]
+    E --> L[Write output]
+    L --> M[.devcontainer/ folder]
+```
+
+## Overlay System
+
+Each overlay is a composable package that can include multiple files:
+
+```
+overlay-name/
+├── devcontainer.patch.json   # Partial config to merge (required)
+├── docker-compose.yml        # Service definition (optional)
+├── .env.example              # Environment variables (optional)
+└── [additional files/dirs]   # Config files, scripts, etc. (optional)
+```
+
+Overlays can add:
+
+- Features
+- Environment variables
+- Port forwards
+- Services (via Docker Compose)
+- Package installations
+
+## Technology Choices
+
+### Node.js/TypeScript
+
+- Cross-platform (Windows, Mac, Linux)
+- Native JSON handling
+- Easy npm/npx distribution
+- Type safety during development
+
+### CLI Libraries
+
+- **chalk** - Terminal colors for better UX
+- **boxen** - Visual hierarchy with borders
+- **ora** - Progress feedback
+- **commander** - Robust argument parsing
+
+### No Framework
+
+Deliberate choice to avoid:
+
+- Complex build pipelines
+- Runtime dependencies in output
+- Learning curve for contributors
+- Version coupling
+
+## Extension Points
+
+### Adding Overlays
+
+1. Create `overlays/<name>/`
+2. Add `overlay.yml` manifest
+3. Add `devcontainer.patch.json`
+4. Optional: Add `docker-compose.yml`
+5. Update questionnaire in `scripts/init.ts`
+
+### Adding Templates
+
+1. Create `templates/<name>/.devcontainer/`
+2. Add standard devcontainer.json
+3. Add scripts and supporting files
+4. Update types in `tool/schema/types.ts`
+5. Add questionnaire option
+
+## Constraints
+
+### What We Don't Do
+
+- ❌ No "update" command (would require state tracking)
+- ❌ No custom DSL (just standard JSON)
+- ❌ No required preprocessing (templates work directly)
+- ❌ No version coupling (output is independent)
+- ❌ No cloud services (purely local operation)
+
+### Why These Constraints
+
+These limitations keep the tool **humble** and prevent it from becoming a platform that users must learn, debug, and maintain. The tool is training wheels, not a framework.
+
+## Success Metrics
+
+The tool succeeds when:
+
+1. Users create their first devcontainer easily
+2. Users edit output directly without the tool
+3. Users don't need the tool after initial setup
+4. Templates work independently of the tool
+
+## Trade-offs
+
+### Advantages
+
+- Low barrier to entry
+- No vendor lock-in
+- Composable and extensible
+- Easy to understand
+- Minimal maintenance burden
+
+### Limitations
+
+- No automatic updates of existing configs
+- Limited validation of composed output
+- Manual effort to keep overlays compatible
+- No rollback mechanism
+
+These limitations are **intentional** to prevent tool creep.