container-superposition 0.1.1 → 0.1.4

package/docs/minimal-and-editor.md

@@ -0,0 +1,265 @@
+# Minimal Mode and Editor Profiles
+
+Container Superposition provides options to customize the generated development environment based on your needs and preferences.
+
+## Minimal Mode
+
+Use `--minimal` to generate lean configurations by excluding optional overlays.
+
+### Usage
+
+```bash
+# Generate minimal configuration
+container-superposition init --minimal
+
+# With other options
+container-superposition init --stack plain --language nodejs --minimal
+
+# Compare: Normal vs Minimal
+container-superposition init --language nodejs --dev-tools modern-cli-tools,git-helpers,codex
+# ✓ Includes: nodejs, modern-cli-tools, git-helpers, codex
+
+container-superposition init --language nodejs --dev-tools modern-cli-tools,git-helpers,codex --minimal
+# ✓ Includes: nodejs (essential)
+# ✗ Excludes: modern-cli-tools, git-helpers, codex (marked as optional)
+```
+
+### What Gets Excluded
+
+Overlays marked with `minimal: true` in their `overlay.yml` are excluded in minimal mode:
+
+- **modern-cli-tools** — Enhanced CLI tools (jq, yq, ripgrep, fd, bat)
+- **git-helpers** — Git LFS, GitHub CLI, GPG/SSH support
+- **codex** — AI-powered coding assistant
+
+Essential overlays (languages, databases, required tools) are always included.
+
+### When to Use Minimal Mode
+
+**CI/CD Environments:**
+
+```bash
+container-superposition init --minimal --stack compose --language nodejs --database postgres
+```
+
+**Resource-Constrained Codespaces:**
+
+```bash
+container-superposition init --minimal --target codespaces --language python
+```
+
+**Learning/Tutorials:**
+
+```bash
+container-superposition init --minimal --stack plain --language nodejs
+```
+
+**Production-like Environments:**
+
+```bash
+container-superposition init --minimal --stack compose --language dotnet --database sqlserver
+```
+
+### Marking Overlays as Optional
+
+When creating overlays, add `minimal: true` to mark them as optional:
+
+```yaml
+# overlays/modern-cli-tools/overlay.yml
+id: modern-cli-tools
+name: Modern CLI Tools
+description: Enhanced command-line tools
+category: dev
+minimal: true # Excluded in minimal mode
+```
+
+## Editor Profiles
+
+Use `--editor` to choose which editor customizations to include.
+
+### Usage
+
+```bash
+# VS Code (default) - Include VS Code extensions and settings
+container-superposition init --editor vscode
+
+# None - CLI-only, no editor customizations
+container-superposition init --editor none
+
+# JetBrains - Skip VS Code customizations (reserved for future JetBrains support)
+container-superposition init --editor jetbrains
+```
+
+### Available Profiles
+
+#### vscode (Default)
+
+Includes VS Code extensions and settings from overlays.
+
+```json
+{
+    "customizations": {
+        "vscode": {
+            "extensions": ["dbaeumer.vscode-eslint", "esbenp.prettier-vscode"],
+            "settings": {
+                "editor.defaultFormatter": "esbenp.prettier-vscode"
+            }
+        }
+    }
+}
+```
+
+#### none
+
+Removes all editor customizations. Useful for:
+
+- CI/CD containers
+- Server environments
+- Terminal-only workflows
+- Using different editors (vim, emacs, etc.)
+
+```json
+{
+    // No customizations field
+}
+```
+
+#### jetbrains
+
+Removes VS Code customizations. Reserved for future JetBrains-specific settings (Gateway, Fleet, etc.).
+
+```json
+{
+    // No vscode customizations
+    // Future: JetBrains-specific settings could be added here
+}
+```
+
+### When to Use Editor Profiles
+
+**Terminal Workflows:**
+
+```bash
+container-superposition init --editor none --language python
+```
+
+**JetBrains IDEs:**
+
+```bash
+container-superposition init --editor jetbrains --language java
+```
+
+**CI/CD (no editor needed):**
+
+```bash
+container-superposition init --editor none --minimal --language nodejs
+```
+
+## Combining Flags
+
+Both flags can be used together with init or regen commands:
+
+```bash
+# Minimal, CLI-only configuration
+container-superposition init --minimal --editor none --language nodejs
+
+# Regenerate existing setup in minimal mode without editor customizations
+container-superposition regen --minimal --editor none
+
+# Resource-efficient Codespaces setup
+container-superposition init --minimal --editor vscode --target codespaces --language python
+
+# Lean JetBrains environment
+container-superposition init --minimal --editor jetbrains --language java
+```
+
+## Regeneration Workflow
+
+The `regen` command is particularly useful when you want to modify an existing setup:
+
+```bash
+# Step 1: Create initial setup with all extras
+container-superposition init --language nodejs --dev-tools modern-cli-tools,git-helpers,codex
+
+# Step 2: Later, regenerate without the extras
+container-superposition regen --minimal
+# Reads existing manifest, excludes optional overlays
+
+# Step 3: Or regenerate for a different editor
+container-superposition regen --editor jetbrains
+# Removes VS Code customizations
+
+# Step 4: Or both together
+container-superposition regen --minimal --editor none
+# Lean, CLI-only regeneration
+```
+
+## Examples
+
+### Minimal Node.js for CI
+
+```bash
+container-superposition init \
+  --minimal \
+  --editor none \
+  --stack plain \
+  --language nodejs \
+  --output .devcontainer
+```
+
+**Result:** Bare-bones Node.js environment, no extras, no editor extensions.
+
+### Full-Featured Local Development
+
+```bash
+container-superposition init \
+  --editor vscode \
+  --stack compose \
+  --language nodejs \
+  --database postgres \
+  --dev-tools docker-sock,git-helpers,modern-cli-tools,pre-commit \
+  --observability prometheus,grafana
+```
+
+**Result:** Complete development environment with all tools and VS Code extensions.
+
+### Codespaces-Optimized Setup
+
+```bash
+container-superposition init \
+  --minimal \
+  --editor vscode \
+  --target codespaces \
+  --stack compose \
+  --language python \
+  --database postgres
+```
+
+**Result:** Lean Codespaces environment with essential tools and VS Code extensions.
+
+## Manifest Support
+
+Both settings are stored in `superposition.json`:
+
+```json
+{
+    "version": "0.1.0",
+    "generated": "2026-02-13T09:00:00.000Z",
+    "minimal": true,
+    "editor": "none",
+    "overlays": ["nodejs"]
+}
+```
+
+Use `container-superposition regen` to regenerate from manifest:
+
+```bash
+# Regenerate with same settings
+container-superposition regen
+```
+
+## See Also
+
+- [CLI Reference](../README.md#cli-usage)
+- [Overlay Authoring](creating-overlays.md)
+- [Deployment Targets](deployment-targets.md)

package/docs/overlay-imports.md

@@ -0,0 +1,209 @@
+# Overlay Imports
+
+Overlays can import shared configuration fragments from `overlays/.shared/` to reduce duplication and ensure consistency across overlays.
+
+## Overview
+
+Import functionality allows overlays to reference common configuration files instead of duplicating them in every overlay. This promotes DRY (Don't Repeat Yourself) principles and makes it easier to maintain consistent patterns.
+
+## Shared Directory Structure
+
+```
+overlays/
+├── .shared/
+│   ├── otel/                           # OpenTelemetry configurations
+│   │   ├── otel-base-config.yaml      # Base OTEL collector config
+│   │   └── instrumentation.env        # Common env vars for instrumentation
+│   ├── compose/                        # Docker Compose patterns
+│   │   └── common-healthchecks.yml    # Standard healthcheck configurations
+│   └── vscode/                         # VS Code extension sets
+│       └── recommended-extensions.json # Commonly recommended extensions
+├── prometheus/
+│   ├── overlay.yml                     # Can import from .shared/
+│   └── devcontainer.patch.json
+└── jaeger/
+    ├── overlay.yml                     # Can import from .shared/
+    └── devcontainer.patch.json
+```
+
+## Using Imports
+
+Add the `imports` field to your `overlay.yml` manifest:
+
+```yaml
+id: prometheus
+name: Prometheus
+description: Metrics collection and monitoring
+category: observability
+supports:
+    - compose
+requires: []
+suggests:
+    - alertmanager
+conflicts: []
+tags:
+    - observability
+    - metrics
+ports:
+    - 9090
+imports:
+    - .shared/otel/instrumentation.env
+    - .shared/compose/common-healthchecks.yml
+```
+
+## Supported File Types
+
+### JSON Files (`.json`)
+
+Merged as devcontainer patches, just like `devcontainer.patch.json`.
+
+**Example: `.shared/vscode/recommended-extensions.json`**
+
+```json
+{
+    "customizations": {
+        "vscode": {
+            "extensions": [
+                "streetsidesoftware.code-spell-checker",
+                "usernamehw.errorlens",
+                "editorconfig.editorconfig"
+            ]
+        }
+    }
+}
+```
+
+### YAML Files (`.yaml`, `.yml`)
+
+Loaded and merged as devcontainer patches. Useful for complex configurations.
+
+**Example: `.shared/otel/otel-base-config.yaml`**
+
+```yaml
+receivers:
+    otlp:
+        protocols:
+            grpc:
+                endpoint: 0.0.0.0:4317
+            http:
+                endpoint: 0.0.0.0:4318
+```
+
+### Environment Files (`.env`)
+
+Merged into `.env.example` with a comment indicating the import source.
+
+**Example: `.shared/otel/instrumentation.env`**
+
+```bash
+# OpenTelemetry Configuration
+OTEL_SERVICE_NAME=my-service
+OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317
+OTEL_TRACES_SAMPLER=always_on
+```
+
+## How Imports Work
+
+1. **Resolution**: Imports are resolved relative to the `overlays/` directory
+2. **Order**: Imports are applied in the order listed, then the overlay's own files
+3. **Merging**:
+    - JSON/YAML: Deep merged into devcontainer configuration
+    - ENV: Concatenated into `.env.example` with source comments
+4. **Validation**: Doctor command validates that all imports exist and are valid
+
+## Benefits
+
+### Reduced Duplication
+
+Before imports:
+
+```
+prometheus/devcontainer.patch.json  (200 lines with OTEL config)
+jaeger/devcontainer.patch.json      (200 lines with OTEL config)
+grafana/devcontainer.patch.json     (200 lines with OTEL config)
+```
+
+After imports:
+
+```
+.shared/otel/otel-base-config.yaml  (50 lines, shared)
+prometheus/overlay.yml              (imports: [.shared/otel/otel-base-config.yaml])
+jaeger/overlay.yml                  (imports: [.shared/otel/otel-base-config.yaml])
+grafana/overlay.yml                 (imports: [.shared/otel/otel-base-config.yaml])
+```
+
+### Consistency
+
+All overlays using the same shared config stay in sync automatically.
+
+### Maintainability
+
+Update shared configuration once, all importing overlays benefit.
+
+## Validation
+
+The `doctor` command validates imports:
+
+```bash
+container-superposition doctor
+```
+
+Checks performed:
+
+- Import files exist
+- File types are supported (`.json`, `.yaml`, `.yml`, `.env`)
+- No broken import references
+
+## Creating Shared Configurations
+
+1. **Identify common patterns** across overlays
+2. **Extract to `.shared/` subdirectory** with descriptive path
+3. **Update overlays** to import the shared file
+4. **Test** that composition works correctly
+5. **Document** the shared file's purpose in `.shared/README.md`
+
+## Example: OTEL Instrumentation
+
+Many observability overlays need OTEL instrumentation. Instead of duplicating these environment variables:
+
+**Create:** `overlays/.shared/otel/instrumentation.env`
+
+```bash
+# OpenTelemetry SDK Configuration
+OTEL_SERVICE_NAME=my-service
+OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317
+OTEL_EXPORTER_OTLP_PROTOCOL=grpc
+OTEL_RESOURCE_ATTRIBUTES=deployment.environment=development
+OTEL_TRACES_SAMPLER=always_on
+OTEL_TRACES_EXPORTER=otlp
+OTEL_METRICS_EXPORTER=otlp
+OTEL_LOGS_EXPORTER=otlp
+```
+
+**Import in overlays:**
+
+```yaml
+# overlays/prometheus/overlay.yml
+imports:
+    - .shared/otel/instrumentation.env
+
+# overlays/jaeger/overlay.yml
+imports:
+    - .shared/otel/instrumentation.env
+```
+
+Now all OTEL-compatible overlays share the same instrumentation configuration!
+
+## Best Practices
+
+1. **Keep shared files focused** - One concern per file
+2. **Use descriptive paths** - `.shared/otel/instrumentation.env` not `.shared/env1.env`
+3. **Document shared files** - Add comments explaining purpose and usage
+4. **Version carefully** - Changes to shared files affect all importing overlays
+5. **Test imports** - Verify overlay composition works after adding imports
+
+## See Also
+
+- [Creating Overlays](creating-overlays.md)
+- [Overlay Metadata](overlay-metadata-archive.md)
+- [Doctor Command](../README.md#doctor-command)

package/docs/overlay-manifest-refactoring.md

@@ -73,7 +73,7 @@ The overlay loader (`tool/schema/overlay-loader.ts`) discovers overlays by:
 3. Validating manifest structure and fields
 4. Grouping overlays by category
 5. Loading base images/templates from `.registry/` files
-6. Loading preset metadata from `overlays/presets/*.yml`
+6. Loading preset metadata from `overlays/.presets/*.yml`
 
 ### Discovery Process
 
@@ -92,7 +92,7 @@ The loader:
 
 ### Preset Handling
 
-Presets are meta-overlays defined in `overlays/presets/*.yml`. Each preset file contains:
+Presets are meta-overlays defined in `overlays/.presets/*.yml`. Each preset file contains:
 
 - Metadata (id, name, description, tags, supports)
 - Selection rules (required overlays, user choices)

package/docs/overlay-metadata-archive.md

@@ -10,7 +10,7 @@ This central `index.yml` file (592 lines) has been split into:
 
 - **46 individual overlay manifests** - `overlays/*/overlay.yml`
 - **Registry files** - `overlays/.registry/base-images.yml` and `base-templates.yml`
-- **Preset definitions** - Individual YAML files in `overlays/presets/*.yml`
+- **Preset definitions** - Individual YAML files in `overlays/.presets/*.yml`
 
 ## New Structure