container-superposition 0.1.1 → 0.1.3

package/README.md

@@ -1,5 +1,9 @@
 # container-superposition
 
+[![Validate Overlays](https://github.com/veggerby/container-superposition/actions/workflows/validate-overlays.yml/badge.svg)](https://github.com/veggerby/container-superposition/actions/workflows/validate-overlays.yml)
+[![Build DevContainers](https://github.com/veggerby/container-superposition/actions/workflows/build-devcontainers.yml/badge.svg)](https://github.com/veggerby/container-superposition/actions/workflows/build-devcontainers.yml)
+[![npm version](https://badge.fury.io/js/container-superposition.svg)](https://www.npmjs.com/package/container-superposition)
+
 Composable devcontainer scaffolds that collapse into working environments.
 
 ## 🎯 Purpose
@@ -253,9 +257,110 @@ npm run init
 
 - **`init`** - Initialize a new devcontainer configuration (default command)
 - **`regen`** - Regenerate devcontainer from existing manifest
-- **`list`** - List all available overlays and presets
+- **`list`** - List all available overlays and presets with filtering options
+- **`explain`** - Show detailed information about a specific overlay
+- **`plan`** - Preview what will be generated before creating devcontainer
 - **`doctor`** - Check environment and validate configuration
 
+#### Discovery Commands
+
+**List available overlays:**
+
+```bash
+# List all overlays grouped by category
+npx container-superposition list
+
+# Filter by category
+npx container-superposition list --category database
+
+# Filter by tags
+npx container-superposition list --tags observability
+
+# Filter by stack support
+npx container-superposition list --supports compose
+
+# JSON output for scripting
+npx container-superposition list --json
+```
+
+**Explain an overlay in detail:**
+
+```bash
+# Show detailed information about an overlay
+npx container-superposition explain postgres
+
+# JSON output
+npx container-superposition explain nodejs --json
+```
+
+**Plan before generating:**
+
+```bash
+# Preview what will be created
+npx container-superposition plan --stack compose --overlays postgres,grafana
+
+# Include port offset
+npx container-superposition plan --stack compose --overlays postgres,redis --port-offset 100
+
+# JSON output
+npx container-superposition plan --stack compose --overlays nodejs,postgres --json
+```
+
+The `plan` command shows:
+
+- Selected overlays and auto-added dependencies
+- Port mappings (with offset applied)
+- Files that will be created/modified
+- Conflict detection
+
+#### Environment Validation
+
+The `doctor` command provides comprehensive environment diagnostics:
+
+```bash
+# Check environment and configuration
+npx container-superposition doctor
+
+# Check specific devcontainer
+npx container-superposition doctor --output /path/to/.devcontainer
+
+# Get JSON output for CI/CD
+npx container-superposition doctor --json
+
+# Apply automatic fixes (where possible)
+npx container-superposition doctor --fix
+```
+
+**Doctor checks:**
+
+- ✅ Node.js version compatibility (>= 18)
+- ✅ Docker daemon connectivity
+- ✅ Docker Compose v2 availability (when using compose stack)
+- ✅ Overlay integrity (valid manifests, required files)
+- ✅ Manifest compatibility
+- ⚠️ Port conflicts (best-effort detection)
+
+**Example output:**
+
+```
+🔍 Running diagnostics...
+
+Environment:
+  ✓ Node.js version: v20.10.0 (>= 18.0.0 required)
+  ✓ Docker daemon: Docker version 24.0.5
+  ✓ Docker Compose: v2.23.0 (v2 required)
+
+Overlays:
+  ✓ All 46 overlays valid
+
+Manifest:
+  ✓ Manifest version: Format version 0.1.0
+  ✓ DevContainer config: devcontainer.json valid
+
+Summary:
+  ✓ 51 passed
+```
+
 The questionnaire guides you through:
 
 1. **Preset or Custom** - Start from a pre-configured stack or build custom?
@@ -357,6 +462,26 @@ npm run init -- --stack compose --language nodejs --postgres --port-offset 200 -
 
 This automatically adjusts all exposed ports in docker-compose.yml and documents the offset in .env.example.
 
+### Deployment Target Support
+
+Container Superposition validates overlay compatibility with different deployment environments (local, Codespaces, Gitpod, DevPod) using the `--target` flag.
+
+```bash
+# Specify deployment target
+npx container-superposition init --target codespaces
+npx container-superposition init --target gitpod
+npx container-superposition init --target local  # default
+```
+
+The tool automatically validates overlay compatibility and warns you when selecting overlays that won't work in your target environment (e.g., `docker-sock` doesn't work in Codespaces).
+
+**📖 See [Deployment Targets Documentation](docs/deployment-targets.md) for:**
+
+- Complete target comparison table
+- Interactive mode examples
+- Environment-specific configuration
+- Compatibility rules and best practices
+
 ### Regenerating from Manifest
 
 Every devcontainer generation creates a `superposition.json` manifest file that records your configuration choices. You can use this manifest to:
@@ -485,6 +610,86 @@ npm run init -- --from-manifest .devcontainer/superposition.json
 
 See **[Custom Patches Guide](docs/custom-patches.md)** for complete documentation and examples.
 
+### Team Collaboration Workflow
+
+**Use Case:** Standardize dev environments across a team while allowing personal customizations.
+
+Container Superposition supports a **manifest-first workflow** where:
+
+- **Manifest** (`superposition.json`) is committed to version control
+- **.devcontainer/** is generated locally and gitignored
+- **Custom patches** (`.devcontainer/custom/`) can be committed for shared customizations
+
+#### Quick Setup
+
+**1. Team lead creates the manifest:**
+
+```bash
+# Generate manifest only (no .devcontainer/ files)
+npx container-superposition init --write-manifest-only \
+  --stack compose \
+  --language nodejs \
+  --database postgres,redis
+
+# Commit to repo
+git add superposition.json .gitignore
+git commit -m "Add team devcontainer manifest"
+```
+
+**2. Add to `.gitignore`:**
+
+```gitignore
+# DevContainer - generated locally
+.devcontainer/
+
+# Except custom directory (personal/shared customizations)
+!.devcontainer/custom/
+```
+
+**3. Team members clone and generate:**
+
+```bash
+git clone <repo>
+cd <repo>
+
+# Generate .devcontainer/ from manifest
+npx container-superposition regen
+
+# Open in VS Code and rebuild container
+code .
+```
+
+**4. Personal customizations (optional):**
+
+```bash
+# Add personal VS Code extensions, themes, etc.
+mkdir -p .devcontainer/custom
+cat > .devcontainer/custom/devcontainer.patch.json << 'EOF'
+{
+  "customizations": {
+    "vscode": {
+      "extensions": ["eamodio.gitlens"],
+      "settings": {
+        "editor.fontSize": 14
+      }
+    }
+  }
+}
+EOF
+
+# Regenerate to apply
+npx container-superposition regen
+```
+
+**Benefits:**
+
+- ✅ One command onboarding for new developers
+- ✅ No lock-in - generated files are plain JSON/YAML
+- ✅ Personal customizations don't conflict with team standard
+- ✅ CI can validate manifest without committing generated files
+
+See **[Team Workflow Guide](docs/team-workflow.md)** for complete documentation, CI examples, and troubleshooting.
+
 ### Option 2: Manual Composition
 
 1. **Copy a base template:**