container-superposition 0.1.1 → 0.1.3

package/overlays/tilt/README.md

@@ -0,0 +1,259 @@
+# Tilt Overlay
+
+Live update and orchestration for Kubernetes development with real-time feedback.
+
+## Features
+
+- **Tilt** - Smart rebuilds and live updates for Kubernetes
+- **Web UI** - Browser-based dashboard on port 10350
+- **Live Updates** - See code changes instantly in K8s
+- **Smart Builds** - Only rebuild what changed
+- **Resource Orchestration** - Manage complex K8s workflows
+- **Multi-service Support** - Handle microservices architectures
+
+## How It Works
+
+This overlay installs Tilt, a development tool that orchestrates your Kubernetes development workflow. Tilt watches your code, automatically rebuilds containers, and updates your Kubernetes cluster when files change.
+
+**Suggested overlays:**
+
+- `kind` - Local Kubernetes cluster
+- `kubectl-helm` - Kubernetes CLI and Helm
+
+**Conflicts:**
+
+- `skaffold` - Alternative K8s build orchestration tool
+
+## Installation
+
+Tilt is installed automatically during devcontainer creation via `setup.sh`:
+
+- Downloads and installs latest Tilt CLI
+- Installs to `/usr/local/bin/tilt`
+- Web UI accessible on port 10350
+
+## Common Commands
+
+### Starting Tilt
+
+```bash
+# Start Tilt with Tiltfile in current directory
+tilt up
+
+# Start Tilt in specific directory
+tilt up --file ./services/api/Tiltfile
+
+# Start without opening browser
+tilt up --hud=false
+
+# Run in CI mode (no interactive UI)
+tilt ci
+```
+
+### Managing Resources
+
+```bash
+# List resources
+tilt get uiresources
+
+# Trigger manual build
+tilt trigger <resource-name>
+
+# Disable a resource
+tilt disable <resource-name>
+
+# Enable a resource
+tilt enable <resource-name>
+```
+
+### Logs and Debugging
+
+```bash
+# View logs
+tilt logs <resource-name>
+
+# Get resource status
+tilt get uiresources <resource-name>
+
+# Dump snapshot for debugging
+tilt dump engine
+```
+
+## Tiltfile Configuration
+
+Create a `Tiltfile` in your project root:
+
+### Basic Example
+
+```python
+# Build Docker image
+docker_build('myapp', '.')
+
+# Deploy to Kubernetes
+k8s_yaml('k8s/deployment.yaml')
+
+# Forward port
+k8s_resource('myapp', port_forwards=8000)
+```
+
+### Live Update Example
+
+```python
+# Build with live update (no rebuild for code changes)
+docker_build('myapp', '.',
+  live_update=[
+    sync('./src', '/app/src'),
+    run('npm install', trigger=['package.json']),
+    restart_container(),
+  ]
+)
+
+k8s_yaml('k8s/deployment.yaml')
+k8s_resource('myapp', port_forwards=8000)
+```
+
+### Multi-Service Example
+
+```python
+# API service
+docker_build('api', './services/api')
+k8s_yaml('./services/api/k8s.yaml')
+k8s_resource('api', port_forwards=3000)
+
+# Frontend service
+docker_build('frontend', './services/frontend')
+k8s_yaml('./services/frontend/k8s.yaml')
+k8s_resource('frontend', port_forwards=8080)
+
+# Database (no rebuild needed)
+k8s_yaml('./infra/postgres.yaml')
+k8s_resource('postgres', port_forwards=5432)
+```
+
+### Custom Buttons
+
+```python
+# Add custom actions to UI
+local_resource(
+  'db-migrate',
+  'kubectl exec -it deploy/api -- npm run migrate',
+  trigger_mode=TRIGGER_MODE_MANUAL,
+  auto_init=False
+)
+```
+
+## Use Cases
+
+- **Microservices development** - Manage multiple services with dependencies
+- **Rapid iteration** - See changes instantly without manual rebuilds
+- **Team development** - Standardize local development workflow
+- **Complex K8s apps** - Orchestrate multi-tier applications
+- **Learning Kubernetes** - Simplified K8s development experience
+
+**Integrates well with:**
+
+- `kind` or `k3d` - Local Kubernetes clusters
+- `kubectl-helm` - Kubernetes CLI and Helm
+- `nodejs`, `python`, `dotnet` - Application development
+- `docker-in-docker` - Docker builds
+
+## Web UI
+
+Access Tilt's web dashboard:
+
+- **URL**: http://localhost:10350
+- **Features**:
+    - Real-time resource status
+    - Build logs and errors
+    - Resource dependencies graph
+    - Manual trigger buttons
+    - Performance metrics
+
+The UI auto-opens when you run `tilt up`.
+
+## Benefits vs Skaffold
+
+| Feature            | Tilt                     | Skaffold              |
+| ------------------ | ------------------------ | --------------------- |
+| **UI**             | ✅ Rich web UI           | ⚠️ CLI only           |
+| **Live Updates**   | ✅ Sophisticated         | ⚠️ Basic              |
+| **Configuration**  | ✅ Programmable (Python) | ⚠️ Declarative (YAML) |
+| **Flexibility**    | ✅ Very flexible         | ⚠️ More opinionated   |
+| **Learning Curve** | ⚠️ Steeper               | ✅ Gentler            |
+| **CI Integration** | ✅ Good                  | ✅ Excellent          |
+
+**When to use Tilt:**
+
+- Need rich UI and debugging tools
+- Want programmable configuration
+- Developing complex microservices
+- Value rapid feedback loops
+
+**When to use Skaffold:**
+
+- Prefer declarative configuration
+- Focus on CI/CD pipelines
+- Want simpler tool
+- Need Google Cloud integration
+
+## Troubleshooting
+
+### Tilt Can't Find Kubernetes
+
+Ensure you have a K8s cluster:
+
+```bash
+# Create kind cluster
+kind create cluster --name dev
+
+# Verify kubectl works
+kubectl cluster-info
+```
+
+### Build Failures
+
+Check build logs in Tilt UI or:
+
+```bash
+tilt logs <resource-name>
+```
+
+### Port Already in Use
+
+Change Tilt UI port:
+
+```bash
+# In Tiltfile
+config.define_string('ui-port', args=False, usage='Tilt UI port')
+cfg = config.parse()
+tilt_port = cfg.get('ui-port', '10350')
+```
+
+Or use port offset when generating devcontainer.
+
+### Live Update Not Working
+
+Ensure your Tiltfile has `live_update` configuration:
+
+```python
+docker_build('myapp', '.',
+  live_update=[
+    sync('./src', '/app/src'),
+    restart_container(),
+  ]
+)
+```
+
+## References
+
+- [Tilt Documentation](https://docs.tilt.dev/)
+- [Tilt Getting Started](https://docs.tilt.dev/tutorial.html)
+- [Tiltfile API Reference](https://docs.tilt.dev/api.html)
+- [Tilt Examples](https://github.com/tilt-dev/tilt-example-html)
+
+**Related Overlays:**
+
+- `kind` - Local Kubernetes cluster (suggested)
+- `kubectl-helm` - Kubernetes CLI and Helm (suggested)
+- `skaffold` - Alternative K8s build tool (conflicts)
+- `docker-in-docker` - Docker builds

package/overlays/tilt/devcontainer.patch.json

@@ -0,0 +1,17 @@
+{
+    "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
+    "features": {
+        "./features/cross-distro-packages": {
+            "apt": "curl",
+            "apk": "curl"
+        }
+    },
+    "forwardPorts": [10350],
+    "portsAttributes": {
+        "10350": {
+            "label": "Tilt UI",
+            "onAutoForward": "openBrowser"
+        }
+    },
+    "postCreateCommand": "bash .devcontainer/scripts/setup-tilt.sh"
+}

package/overlays/tilt/overlay.yml

@@ -0,0 +1,19 @@
+id: tilt
+name: Tilt
+description: Live update and orchestration for Kubernetes development
+category: dev
+supports: []
+requires: []
+suggests:
+    - kind
+    - kubectl-helm
+conflicts:
+    - skaffold
+tags:
+    - dev
+    - kubernetes
+    - k8s
+    - development
+    - live-reload
+ports:
+    - 10350

package/overlays/tilt/setup.sh

@@ -0,0 +1,25 @@
+#!/bin/bash
+# Setup script for Tilt
+
+set -e
+
+echo "🔧 Setting up Tilt..."
+
+# Install Tilt
+echo "📦 Installing Tilt..."
+
+curl -fsSL https://raw.githubusercontent.com/tilt-dev/tilt/master/scripts/install.sh | bash
+
+# Verify installation
+if command -v tilt &> /dev/null; then
+    echo "✅ Tilt installed successfully"
+    tilt version
+else
+    echo "❌ Tilt installation failed"
+    exit 1
+fi
+
+echo "✅ Tilt setup complete"
+echo ""
+echo "ℹ️  To start Tilt, run:"
+echo "   tilt up"

package/overlays/tilt/verify.sh

@@ -0,0 +1,24 @@
+#!/bin/bash
+# Verification script for Tilt overlay
+# Confirms Tilt is installed
+
+set -e
+
+echo "🔍 Verifying Tilt overlay..."
+echo ""
+
+# Check Tilt is installed
+echo "1️⃣ Checking Tilt installation..."
+if command -v tilt &> /dev/null; then
+    tilt version
+    echo "   ✅ Tilt is installed"
+else
+    echo "   ❌ Tilt is not installed"
+    exit 1
+fi
+
+echo ""
+echo "✅ Tilt overlay verification complete"
+echo ""
+echo "ℹ️  To start Tilt, run:"
+echo "   tilt up"

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "container-superposition",
-    "version": "0.1.1",
+    "version": "0.1.3",
     "description": "Solution-ready devcontainer templates and features with guided initialization",
     "type": "module",
     "main": "dist/scripts/init.js",
@@ -14,7 +14,9 @@
         "test": "vitest run",
         "test:watch": "vitest",
         "test:smoke": "bash scripts/test.sh",
-        "docs:generate": "tsx docs/generate-docs.ts",
+        "docs:generate": "tsx docs/generate-docs.ts && prettier --write docs/overlays.md",
+        "lint": "tsc --noEmit && npm run format:check",
+        "lint:fix": "npm run format",
         "format": "prettier --write \"**/*.{ts,js,json,md,yaml,yml}\"",
         "format:check": "prettier --check \"**/*.{ts,js,json,md,yaml,yml}\"",
         "clean": "rm -rf dist",
@@ -53,15 +55,15 @@
     "dependencies": {
         "@inquirer/checkbox": "^5.0.4",
         "@inquirer/prompts": "^8.2.0",
-        "boxen": "^7.1.1",
+        "boxen": "^8.0.1",
         "chalk": "^5.6.2",
-        "commander": "^12.1.0",
+        "commander": "^14.0.3",
         "js-yaml": "^4.1.1",
-        "ora": "^8.2.0"
+        "ora": "^9.3.0"
     },
     "devDependencies": {
         "@types/js-yaml": "^4.0.9",
-        "@types/node": "^20.19.33",
+        "@types/node": "^25.2.3",
         "@vitest/ui": "^4.0.18",
         "prettier": "^3.4.2",
         "tsx": "^4.7.0",

package/tool/README.md

@@ -103,6 +103,7 @@ This makes the questionnaire more engaging and the output easier to scan.
 | `--cloud-tools <list>`   | Cloud tools: `aws-cli`, `azure-cli`, `gcloud`, `kubectl-helm`, `terraform`, `pulumi`                                                                                  | `--cloud-tools aws-cli,kubectl-helm`        |
 | `--dev-tools <list>`     | Development tools: `docker-in-docker`, `docker-sock`, `playwright`, `codex`, `git-helpers`, `pre-commit`, `commitlint`, `just`, `direnv`, `modern-cli-tools`, `ngrok` | `--dev-tools docker-in-docker,playwright`   |
 | `--port-offset <number>` | Add offset to all exposed ports (e.g., 100 makes Grafana 3100)                                                                                                        | `--port-offset 100`                         |
+| `--target <environment>` | Deployment target: local, codespaces, gitpod, devpod (validates compatibility)                                                                                        | `--target codespaces`                       |
 | `-o`, `--output <path>`  | Output directory (default: `./.devcontainer`)                                                                                                                         | `-o ./custom-path`                          |
 | `-h`, `--help`           | Show help                                                                                                                                                             | `--help`                                    |
 
@@ -121,21 +122,16 @@ After running the tool, you'll have:
 ```
 .devcontainer/
 ├── devcontainer.json                  # Main configuration (editable!)
-├── docker-compose.yml                 # Base compose file (if using compose template)
+├── docker-compose.yml                 # Combined compose file with selected services
 ├── .env.example                       # Environment variables from selected overlays
 ├── scripts/
 │   └── post_create.sh                 # Post-creation scripts
-├── docker-compose.postgres.yml        # (if postgres selected)
-├── docker-compose.redis.yml           # (if redis selected)
-├── docker-compose.otel-collector.yml  # (if otel-collector selected)
-├── docker-compose.jaeger.yml          # (if jaeger selected)
-├── docker-compose.prometheus.yml      # (if prometheus selected)
-├── docker-compose.grafana.yml         # (if grafana selected)
-├── docker-compose.loki.yml            # (if loki selected)
-├── otel-collector-config.yaml         # (if otel-collector selected)
-├── prometheus.yml                     # (if prometheus selected)
-├── grafana-datasources.yml            # (if grafana selected)
-└── loki-config.yaml                   # (if loki selected)
+├── otel-collector-config-otel-collector.yaml  # (if otel-collector selected)
+├── prometheus-prometheus.yml                  # (if prometheus selected)
+├── grafana-datasources-grafana.yml            # (if grafana selected)
+├── dashboard-provider-grafana.yml             # (if grafana selected)
+├── dashboards-grafana/                        # (if grafana selected)
+└── loki-config-loki.yaml                      # (if loki selected)
 ```
 
 All `.env.example` files from selected overlays are automatically merged into a single file with all relevant environment variables.
@@ -192,17 +188,17 @@ Each overlay is a composable package that can include:
 ```
 overlays/postgres/
 ├── devcontainer.patch.json    # Features, env vars, ports (merged into devcontainer.json)
-├── docker-compose.yml         # Service definition (copied as docker-compose.{overlay}.yml)
+├── docker-compose.yml         # Service definition (merged into output docker-compose.yml)
 ├── .env.example               # Environment variables (merged into combined .env.example)
-└── [additional files]         # Config files, scripts, directories (copied as-is)
+└── [additional files]         # Copied with overlay suffix to avoid filename conflicts
 ```
 
 The tool intelligently handles each file type:
 
 - **devcontainer.patch.json** - Deep-merged into devcontainer.json (arrays concatenated, objects merged)
-- **docker-compose.yml** - Copied as `docker-compose.{overlay}.yml` and referenced in devcontainer.json
+- **docker-compose.yml** - Merged with base compose into one output `docker-compose.yml`
 - **.env.example** - Content merged into combined `.env.example` in output
-- **Other files/directories** - Copied as-is to output (e.g., `otel-collector.yml`, `config/redis.conf`)
+- **Other files/directories** - Copied with an overlay suffix (e.g., `prometheus-prometheus.yml`, `dashboards-grafana/`)
 
 This allows overlays to provide complete, self-contained configurations including any necessary config files.
 

package/tool/schema/overlay-manifest.schema.json

@@ -68,11 +68,58 @@
         },
         "ports": {
             "type": "array",
-            "description": "Ports used by the overlay (for offset calculation)",
+            "description": "Ports used by the overlay (for offset calculation and documentation)",
             "items": {
-                "type": "integer",
-                "minimum": 1,
-                "maximum": 65535
+                "oneOf": [
+                    {
+                        "type": "integer",
+                        "minimum": 1,
+                        "maximum": 65535,
+                        "description": "Simple port number (legacy format)"
+                    },
+                    {
+                        "type": "object",
+                        "description": "Rich port metadata with service info and connection details",
+                        "required": ["port"],
+                        "properties": {
+                            "port": {
+                                "type": "integer",
+                                "minimum": 1,
+                                "maximum": 65535,
+                                "description": "Port number"
+                            },
+                            "service": {
+                                "type": "string",
+                                "description": "Service name (e.g., postgres, grafana, jaeger)",
+                                "pattern": "^[a-z0-9-]+$"
+                            },
+                            "protocol": {
+                                "type": "string",
+                                "description": "Protocol type",
+                                "enum": ["http", "https", "tcp", "udp", "grpc"]
+                            },
+                            "description": {
+                                "type": "string",
+                                "description": "Human-readable description of what this port is for"
+                            },
+                            "path": {
+                                "type": "string",
+                                "description": "Default path for HTTP/HTTPS services (e.g., /, /metrics)",
+                                "pattern": "^/"
+                            },
+                            "onAutoForward": {
+                                "type": "string",
+                                "description": "VS Code port auto-forward behavior",
+                                "enum": ["notify", "openBrowser", "openPreview", "silent", "ignore"]
+                            },
+                            "connectionStringTemplate": {
+                                "type": "string",
+                                "description": "Template for connection string (e.g., postgresql://{user}:{password}@{host}:{port}/{database})"
+                            }
+                        },
+                        "additionalProperties": false
+                    }
+                ]
             },
             "default": []
         },
@@ -80,6 +127,19 @@
             "type": "integer",
             "description": "Display order within category (lower = first)",
             "minimum": 1
+        },
+        "imports": {
+            "type": "array",
+            "description": "Shared files to import from overlays/.shared/",
+            "items": {
+                "type": "string"
+            },
+            "default": []
+        },
+        "minimal": {
+            "type": "boolean",
+            "description": "Whether this overlay is excluded in minimal mode (true = extra/optional)",
+            "default": false
         }
     },
     "additionalProperties": false

package/tool/schema/superposition-manifest.schema.json

@@ -0,0 +1,104 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "type": "object",
+    "title": "Superposition Manifest",
+    "description": "Manifest file (superposition.json) generated by container-superposition to track devcontainer configuration",
+    "properties": {
+        "manifestVersion": {
+            "type": "string",
+            "description": "Schema version of the manifest (increments on breaking changes)",
+            "pattern": "^[0-9]+$"
+        },
+        "generatedBy": {
+            "type": "string",
+            "description": "Version of container-superposition that created this manifest"
+        },
+        "version": {
+            "type": "string",
+            "description": "Legacy field for backward compatibility (deprecated, use manifestVersion instead)"
+        },
+        "generated": {
+            "type": "string",
+            "format": "date-time",
+            "description": "ISO 8601 timestamp when the manifest was generated"
+        },
+        "baseTemplate": {
+            "type": "string",
+            "enum": ["plain", "compose"],
+            "description": "Base devcontainer template used (plain for single image, compose for multi-service)"
+        },
+        "baseImage": {
+            "type": "string",
+            "description": "Base container image used for the devcontainer"
+        },
+        "overlays": {
+            "type": "array",
+            "items": {
+                "type": "string"
+            },
+            "description": "List of overlay IDs that were applied to create this configuration"
+        },
+        "portOffset": {
+            "type": "number",
+            "minimum": 0,
+            "description": "Port offset applied to all service ports (optional)"
+        },
+        "preset": {
+            "type": "string",
+            "description": "ID of the preset used to generate this configuration (optional)"
+        },
+        "presetChoices": {
+            "type": "object",
+            "additionalProperties": {
+                "type": "string"
+            },
+            "description": "User choices made within preset user-choice sections (optional)"
+        },
+        "autoResolved": {
+            "type": "object",
+            "properties": {
+                "added": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    },
+                    "description": "List of overlays that were automatically added as dependencies"
+                },
+                "reason": {
+                    "type": "string",
+                    "description": "Human-readable reason why dependencies were added"
+                }
+            },
+            "required": ["added", "reason"],
+            "description": "Information about automatically resolved dependencies (optional)"
+        },
+        "containerName": {
+            "type": "string",
+            "description": "Name of the container/project from devcontainer.json (optional)"
+        },
+        "customizations": {
+            "type": "object",
+            "properties": {
+                "enabled": {
+                    "type": "boolean",
+                    "description": "Whether custom patches are enabled"
+                },
+                "location": {
+                    "type": "string",
+                    "description": "Path to custom patches directory relative to workspace"
+                }
+            },
+            "required": ["enabled", "location"],
+            "description": "Information about custom patches/overrides (optional)"
+        }
+    },
+    "required": [
+        "manifestVersion",
+        "generatedBy",
+        "generated",
+        "baseTemplate",
+        "baseImage",
+        "overlays"
+    ],
+    "additionalProperties": false
+}