container-superposition 0.1.5 → 0.1.7

package/docs/specs/003-mkdocs2-overlay/spec.md

@@ -0,0 +1,114 @@
+# Feature Specification: MkDocs 2.x Overlay
+
+**Feature Branch**: `copilot/add-mkdocs2-overlay`
+**Created**: 2026-03-16
+**Status**: Final
+**Input**: Add a new `mkdocs2` overlay that installs MkDocs 2.x with the Material theme via direct `pip` install, keeping the existing `mkdocs` (MkDocs 1.x) overlay untouched for backward compatibility.
+
+## Review & Approval _(mandatory before implementation)_
+
+- **Spec Path**: `docs/specs/003-mkdocs2-overlay/spec.md`
+- **Commit Status**: Committed
+- **Review Status**: Approved
+- **Implementation Gate**: No implementation code may begin until this spec is committed and reviewed.
+
+## User Scenarios & Testing _(mandatory)_
+
+### User Story 1 - Use MkDocs 2.x in a devcontainer (Priority: P1)
+
+A developer wants to write documentation using MkDocs 2.x with the Material theme inside a devcontainer without manually managing Python packages.
+
+**Why this priority**: MkDocs 2.x is the currently maintained release. Users starting new documentation projects need a working overlay that installs the supported version.
+
+**Independent Test**: Select the `mkdocs2` overlay (with `python` as a required dependency), rebuild the container, and confirm that `mkdocs --version` reports a 2.x release, `mkdocs new .` succeeds, and `mkdocs serve` starts the dev server on port 8000.
+
+**Acceptance Scenarios**:
+
+1. **Given** a user selects the `mkdocs2` overlay, **When** the devcontainer is built, **Then** `mkdocs --version` reports a version matching `2.x`.
+2. **Given** the container is running, **When** the user runs `mkdocs serve`, **Then** the development server starts on port 8000 and VS Code forwards the port automatically.
+3. **Given** a `mkdocs.yml` with `theme: {name: material}`, **When** the user runs `mkdocs build`, **Then** the site is generated without errors into the `site/` directory.
+
+---
+
+### User Story 2 - Conflict enforcement between mkdocs and mkdocs2 (Priority: P1)
+
+A user selects both `mkdocs` (1.x) and `mkdocs2` (2.x) and expects the tool to report a conflict.
+
+**Why this priority**: Both overlays install incompatible versions of the `mkdocs` command into the same environment. Allowing both would produce unpredictable results.
+
+**Independent Test**: Attempt to generate a devcontainer with both `mkdocs` and `mkdocs2` selected and confirm the tool surfaces a conflict and blocks generation.
+
+**Acceptance Scenarios**:
+
+1. **Given** a user selects `mkdocs` and `mkdocs2` simultaneously, **When** the questionnaire processes the selection, **Then** a conflict is reported and the user is prompted to choose one.
+2. **Given** `mkdocs` conflicts with `mkdocs2` in `overlays/mkdocs/overlay.yml`, **When** the overlay loader reads both manifests, **Then** the conflict is recognised bidirectionally.
+
+---
+
+### User Story 3 - Backward compatibility for existing mkdocs users (Priority: P2)
+
+An existing user who already has the `mkdocs` overlay selected is unaffected by the addition of the new overlay.
+
+**Why this priority**: Introducing a new overlay must not break users who rely on the existing one.
+
+**Independent Test**: Generate a devcontainer using only the `mkdocs` overlay and confirm the output is identical to what it was before `mkdocs2` was added.
+
+**Acceptance Scenarios**:
+
+1. **Given** a user's `superposition.json` references only `mkdocs`, **When** they run `regen`, **Then** the output is identical to before and contains no `mkdocs2`-related changes.
+
+---
+
+## Design
+
+### Installation Method
+
+The `mkdocs2` overlay installs packages via `pip` directly into the workspace
+`.venv` virtual environment (created by the `python` overlay, which is a hard
+dependency). The overlay's `setup.sh` creates the `.venv` if it does not exist
+yet, so it is self-contained even when run before the `python` overlay's setup
+script completes.
+
+```bash
+pip install --no-cache-dir \
+    "mkdocs>=2.0,<3.0" \
+    "mkdocs-material>=9.0" \
+    "mkdocs-minify-plugin" \
+    "mkdocs-redirects" \
+    "pymdown-extensions"
+```
+
+This approach is preferred over the `ghcr.io/devcontainers-extra/features/mkdocs:2`
+devcontainer feature because it gives precise version control and installs into
+the same virtual environment used by the rest of the project.
+
+### Category
+
+`dev` — MkDocs is a documentation tool, not a language runtime. This differs
+from the legacy `mkdocs` overlay which uses `language` for historical reasons.
+
+### Conflict Model
+
+`mkdocs` ↔ `mkdocs2` conflict is bidirectional:
+
+- `overlays/mkdocs/overlay.yml`: `conflicts: [mkdocs2]`
+- `overlays/mkdocs2/overlay.yml`: `conflicts: [mkdocs]`
+
+### TypeScript Type
+
+`mkdocs2` is added to the `DevTool` union in `tool/schema/types.ts`, making it
+part of the `OverlayId` union used throughout the type system.
+
+---
+
+## Files
+
+| File                                       | Description                                        |
+| ------------------------------------------ | -------------------------------------------------- |
+| `overlays/mkdocs2/overlay.yml`             | Overlay manifest                                   |
+| `overlays/mkdocs2/devcontainer.patch.json` | Port 8000 forwarding + VS Code Markdown extensions |
+| `overlays/mkdocs2/setup.sh`                | Pip install into `.venv`                           |
+| `overlays/mkdocs2/verify.sh`               | Confirms MkDocs 2.x is installed                   |
+| `overlays/mkdocs2/README.md`               | User documentation                                 |
+| `overlays/mkdocs/overlay.yml`              | Updated to add bidirectional conflict              |
+| `tool/schema/types.ts`                     | Adds `mkdocs2` to `DevTool`                        |

package/docs/specs/004-doctor-fix/spec.md

@@ -0,0 +1,70 @@
+# Feature Specification: `doctor --fix` — Interactive Auto-Repair
+
+**Feature Branch**: `004-doctor-fix`
+**Created**: 2026-03-19
+**Status**: Final
+**Input**: GitHub issue: Implement `doctor --fix` — interactive auto-repair for environment issues
+
+## Review & Approval _(mandatory before implementation)_
+
+- **Spec Path**: `docs/specs/004-doctor-fix/spec.md`
+- **Commit Status**: Committed
+- **Review Status**: APPROVED
+- **Implementation Gate**: No implementation code may begin until this spec is committed and reviewed.
+
+## Summary
+
+The `doctor` command validates the environment. The `--fix` path was a placeholder. This spec
+describes the full implementation of an interactive, safe, deterministic auto-repair flow for
+common environment issues.
+
+## Initial Auto-Fix Scope
+
+| #   | Issue class                                                   | Automation condition                                              |
+| --- | ------------------------------------------------------------- | ----------------------------------------------------------------- |
+| 1   | Stale or legacy `superposition.json` metadata                 | Always supported (manifest migration)                             |
+| 2   | Derived `.devcontainer/` drift or missing generated artifacts | Supported when a valid manifest is present (regeneration)         |
+| 3   | Unsupported Node runtime                                      | Supported only when `nvm`, `fnm`, or `volta` is already available |
+| 4   | Docker / Compose tooling drift                                | Supported only when a known safe host repair command is available |
+
+## Outcome Vocabulary
+
+Every finding evaluated by the fix flow resolves to exactly one of:
+
+- **`fixed`** — tool changed the environment and targeted re-check now passes
+- **`already compliant`** — fix path found no change was needed
+- **`skipped`** — not attempted because an earlier failure or prerequisite blocked it
+- **`requires manual action`** — issue remains; automation is unsafe or unavailable
+
+## Data Model
+
+### `DiagnosticFinding`
+
+Fields: `id`, `category`, `name`, `status`, `message`, `details?`, `fixEligibility`, `remediationKey?`, `recheckScope`
+
+### `RemediationAction`
+
+Fields: `key`, `findingId`, `safetyClass`, `executionKind`, `preconditions`, `plannedChanges`, `manualFallback`
+
+### `FixExecution`
+
+Fields: `findingId`, `remediationKey`, `attempted`, `outcome`, `reason`, `commands?`, `changedFiles?`, `backupPath?`, `rechecked`
+
+### `FixRun`
+
+Fields: `outputPath`, `requestedJson`, `initialFindings`, `executions`, `finalFindings`, `summary`, `exitDisposition`
+
+## CLI Contract
+
+- `doctor` without `--fix` — no change to current diagnostics behavior
+- `doctor --fix` — diagnose → remediate in stable order → re-check → print summary
+- `doctor --fix --json` — same flow, machine-readable JSON output
+
+## Remediation Ordering
+
+Prerequisites before dependents:
+
+1. Stale manifest migration (must complete before regeneration)
+2. Missing artifacts / devcontainer drift (regeneration from manifest)
+3. Node version fix (only if version manager available)
+4. Docker tooling fix (only if repair command available)

package/docs/specs/005-cuda-overlay/spec.md

@@ -0,0 +1,101 @@
+# Feature Specification: CUDA (NVIDIA GPU) Overlay
+
+**Feature Branch**: `copilot/add-cuda-overlay-for-gpu`
+**Created**: 2026-03-22
+**Status**: Final
+**Input**: Add a `cuda` overlay to enable NVIDIA GPU-accelerated workloads inside a dev container.
+
+## Review & Approval _(mandatory before implementation)_
+
+- **Spec Path**: `docs/specs/005-cuda-overlay/spec.md`
+- **Commit Status**: Committed
+- **Review Status**: Approved
+- **Implementation Gate**: No implementation code may begin until this spec is committed and reviewed.
+
+## User Scenarios & Testing _(mandatory)_
+
+### User Story 1 - GPU passthrough for ML/inference workloads (Priority: P1)
+
+A developer wants to run NVIDIA GPU-accelerated workloads (ML training, inference, CUDA compute) inside a dev container without manually configuring Docker runtime flags.
+
+**Why this priority**: GPU-accelerated dev containers require specific Docker runtime flags (`--gpus=all`) and VS Code devcontainer host requirements (`gpu: true`) that must be set correctly for the container to access the GPU. Without the overlay, users must add these manually and correctly every time.
+
+**Independent Test**: Select the `cuda` overlay, rebuild the container, and confirm that `nvidia-smi` exits 0 and reports the GPU correctly.
+
+**Acceptance Scenarios**:
+
+1. **Given** a user selects the `cuda` overlay, **When** the devcontainer is built, **Then** `devcontainer.json` includes `"runArgs": ["--gpus=all"]` and `"hostRequirements": {"gpu": true}`.
+2. **Given** the NVIDIA Container Toolkit is installed on the host, **When** the devcontainer starts, **Then** `nvidia-smi` is accessible inside the container.
+3. **Given** the container is running, **When** `setup.sh` executes, **Then** it reports whether `nvidia-smi` is available and prints a helpful message if it is not.
+
+---
+
+### User Story 2 - Conflict enforcement between cuda and rocm (Priority: P1)
+
+A user selects both `cuda` and `rocm` and expects the tool to report a conflict, because only one GPU compute framework can be active at a time.
+
+**Why this priority**: CUDA (NVIDIA) and ROCm (AMD) are mutually exclusive GPU compute frameworks. Allowing both would produce an incoherent configuration.
+
+**Independent Test**: Attempt to generate a devcontainer with both `cuda` and `rocm` selected and confirm the tool surfaces a conflict and blocks generation.
+
+**Acceptance Scenarios**:
+
+1. **Given** a user selects both `cuda` and `rocm`, **When** they run `container-superposition init`, **Then** the tool reports a conflict and prevents generation.
+2. **Given** `cuda` lists `rocm` in `conflicts`, **When** `rocm` is added in the future, **Then** `rocm` must also list `cuda` in its `conflicts` (bidirectional enforcement). Note: `rocm` does not exist yet; when it is added the reciprocal conflict must be declared in `overlays/rocm/overlay.yml`.
+
+---
+
+## Design
+
+### overlay.yml
+
+```yaml
+id: cuda
+name: CUDA (NVIDIA GPU)
+description: NVIDIA CUDA libraries and GPU passthrough for containerized ML/inference workloads
+category: dev
+supports: []
+requires: []
+suggests: []
+conflicts:
+    - rocm
+tags:
+    - gpu
+    - cuda
+    - nvidia
+    - ml
+    - inference
+ports: []
+```
+
+### devcontainer.patch.json
+
+Set `runArgs` for GPU passthrough and `hostRequirements` to signal GPU need:
+
+```json
+{
+    "runArgs": ["--gpus=all"],
+    "hostRequirements": { "gpu": true }
+}
+```
+
+### setup.sh
+
+- Check whether `nvidia-smi` is reachable inside the container.
+- Print a helpful message if it is not (host driver / toolkit not configured).
+
+### verify.sh
+
+- Assert `nvidia-smi` exits 0 (used by the `doctor` command).
+
+### README.md
+
+- Clear prerequisites section (host drivers, NVIDIA Container Toolkit).
+- Troubleshooting tips for common failure modes.
+- Note that the overlay does not replace or install host drivers.
+
+## Out of Scope
+
+- Installing or replacing host NVIDIA drivers.
+- Guaranteeing version alignment between CUDA user-space libraries and the host kernel module.
+- ROCm (AMD GPU) support — tracked separately.

package/docs/specs/006-rocm-overlay/spec.md

@@ -0,0 +1,109 @@
+# Feature Specification: ROCm (AMD GPU) Overlay
+
+**Feature Branch**: `copilot/add-rocm-overlay`
+**Created**: 2026-03-22
+**Status**: Accepted
+**Input**: Add a `rocm` overlay to enable AMD GPU-accelerated workloads inside a dev container.
+
+## Review & Approval _(mandatory before implementation)_
+
+- **Spec Path**: `docs/specs/006-rocm-overlay/spec.md`
+- **Commit Status**: Committed
+- **Review Status**: Approved
+- **Implementation Gate**: No implementation code may begin until this spec is committed and reviewed.
+
+## Overview
+
+Add a `rocm` overlay to enable AMD GPU-accelerated workloads inside a dev container using the ROCm open software platform.
+
+> **Note:** ROCm-in-container is a supported but more fragile path than CUDA. It depends heavily on the host kernel version, AMD driver stack, specific device support, and container runtime configuration. Treat this as a separate supported profile — not a drop-in equivalent of CUDA.
+
+## User Scenarios & Testing _(mandatory)_
+
+### User Story 1 - AMD GPU passthrough for ML/inference workloads (Priority: P1)
+
+1. **Given** a user selects the `rocm` overlay, **When** the devcontainer is built, **Then** `devcontainer.json` includes `"runArgs": ["--device=/dev/kfd", "--device=/dev/dri", "--group-add=video", "--group-add=render"]`.
+2. **Given** the AMD GPU drivers and ROCm runtime are installed on the host, **When** the devcontainer starts, **Then** `rocm-smi` is accessible inside the container.
+3. **Given** the container is running, **When** `setup.sh` executes, **Then** it reports whether `rocm-smi` is available and prints a helpful message if it is not.
+4. **Given** `rocm-smi` is not available, **When** `verify.sh` executes, **Then** it exits 1 for the `doctor` command.
+
+---
+
+## Prerequisites (host-side — out of scope for this overlay)
+
+1. Supported AMD GPU hardware (RDNA 2+, most CDNA — check [ROCm hardware support matrix](https://rocm.docs.amd.com/en/latest/compatibility/compatibility-matrix.html))
+2. AMD GPU drivers (`amdgpu`) installed on the host
+3. ROCm runtime installed on the host (or the container image bundles it)
+4. User added to the `render` and `video` groups, or appropriate device permissions set
+5. `/dev/kfd` and `/dev/dri` devices accessible in the container
+
+## Design
+
+### overlay.yml
+
+```yaml
+id: rocm
+name: ROCm (AMD GPU)
+description: AMD ROCm libraries and GPU passthrough for containerized ML/inference workloads
+category: dev
+supports: []
+requires: []
+suggests: []
+conflicts:
+    - cuda
+tags:
+    - dev
+    - gpu
+    - rocm
+    - amd
+    - ml
+    - inference
+ports: []
+```
+
+### devcontainer.patch.json
+
+Set `runArgs` for AMD GPU device passthrough:
+
+```json
+{
+    "runArgs": ["--device=/dev/kfd", "--device=/dev/dri", "--group-add=video", "--group-add=render"]
+}
+```
+
+- `/dev/kfd` — AMD Kernel Fusion Driver; required for ROCm compute
+- `/dev/dri` — Direct Rendering Infrastructure; gives access to GPU render nodes
+- `--group-add=video` and `--group-add=render` — add the container user to the groups that own the GPU device nodes
+
+### setup.sh
+
+- Check whether `rocm-smi` or `rocminfo` is reachable inside the container.
+- Print a helpful message if neither is found (host driver / ROCm not configured).
+
+### verify.sh
+
+- Assert `rocm-smi` exits 0 (used by the `doctor` command).
+
+### README.md
+
+Must include:
+
+- Prominent prerequisites section
+- Known limitations (kernel version coupling, device node names may vary)
+- ROCm framework wheels (PyTorch ROCm, TensorFlow ROCm)
+- Troubleshooting section
+- Link to ROCm compatibility matrix
+- Clear note that this overlay does not replace host drivers
+
+## Relationship to CUDA Overlay
+
+- `cuda` and `rocm` must list each other in `conflicts` (bidirectional, per project rules)
+- The `cuda` overlay already declares `rocm` in its `conflicts`
+- CUDA is considered the primary GPU path; ROCm is a supported secondary path
+
+## Known Constraints and Caveats
+
+- ROCm version support is tightly coupled to kernel and driver versions
+- Device node names (`/dev/dri/renderD128`) may differ per host
+- Some frameworks publish separate ROCm wheels
+- Less forgiving than CUDA during setup — detailed troubleshooting is essential

package/docs/team-workflow.md

@@ -44,6 +44,9 @@ npx container-superposition adopt --dry-run
 
 # Run the adoption (writes superposition.json and custom/ patches)
 npx container-superposition adopt
+
+# Or also emit a repository-root project file for project-config workflows
+npx container-superposition adopt --project-file
 ```
 
 `adopt` reads every feature URI, VS Code extension, and Docker Compose service
@@ -54,7 +57,10 @@ mounts, unmatched environment variables, …) is written to
 
 `superposition.json` is written to the **project root** (not inside
 `.devcontainer/`), so it can be committed alongside your application code and
-shared with the rest of the team — matching the standard team workflow.
+shared with the rest of the team — matching the standard team workflow. If you
+pass `--project-file`, `adopt` also writes a repository-root `.superposition.yml`
+using the same inferred stack, overlays, output path, and supported
+customizations.
 
 See the [Adopt Command guide](adopt.md) for full details.
 

package/docs/workflows.md

@@ -68,6 +68,9 @@ npx container-superposition regen
 # Or select the project file explicitly
 npx container-superposition regen --from-project
 
+# Or run from another directory while targeting a repository root
+npx container-superposition regen --from-project --project-root ../my-project
+
 # Falls back to manifest discovery when no project file exists
 npx container-superposition regen
 ```

package/features/cross-distro-packages/README.md

@@ -6,6 +6,7 @@ A devcontainer feature that installs system packages with automatic distribution
 
 - 🔍 **Auto-detection**: Automatically detects whether the container uses apt or apk
 - 📦 **Distro-specific packages**: Specify different package names for each distribution
+- 🔁 **Fallback package names**: Use `pkgA|pkgB` when Debian/Ubuntu variants expose different names
 - 🧹 **Clean installation**: Cleans up package manager caches to minimize image size
 - ⚡ **Fast**: No unnecessary updates or cache rebuilds
 
@@ -26,6 +27,19 @@ A devcontainer feature that installs system packages with automatic distribution
 
 ### Real-World Examples
 
+**Fallback package names within apt-based distros:**
+
+```json
+{
+    "features": {
+        "./features/cross-distro-packages": {
+            "apt": "fonts-carlito|fonts-crosextra-carlito",
+            "apk": ""
+        }
+    }
+}
+```
+
 **Node.js Build Tools:**
 
 ```json
@@ -85,6 +99,10 @@ A devcontainer feature that installs system packages with automatic distribution
 | `apt`  | string | `""`    | Space-separated list of packages for apt-based distributions (Debian, Ubuntu) |
 | `apk`  | string | `""`    | Space-separated list of packages for apk-based distributions (Alpine Linux)   |
 
+Package entries may include fallback candidates separated by `|`, for example
+`fonts-carlito|fonts-crosextra-carlito`. The feature selects the first package
+name that exists for the detected package manager.
+
 ## Package Name Differences
 
 Common packages that have different names across distributions:

package/features/cross-distro-packages/devcontainer-feature.json

@@ -2,18 +2,18 @@
     "id": "cross-distro-packages",
     "version": "1.0.0",
     "name": "Cross-Distribution Package Manager",
-    "description": "Install system packages with automatic distribution detection (supports apt and apk)",
+    "description": "Install system packages with automatic distribution detection and fallback package-name support (supports apt and apk)",
     "documentationURL": "https://github.com/veggerby/container-superposition/tree/main/features/cross-distro-packages",
     "options": {
         "apt": {
             "type": "string",
             "default": "",
-            "description": "Space-separated list of packages for apt-based distros (Debian, Ubuntu)"
+            "description": "Space-separated list of packages for apt-based distros (Debian, Ubuntu). Use pkgA|pkgB to try fallback names."
         },
         "apk": {
             "type": "string",
             "default": "",
-            "description": "Space-separated list of packages for apk-based distros (Alpine)"
+            "description": "Space-separated list of packages for apk-based distros (Alpine). Use pkgA|pkgB to try fallback names."
         }
     },
     "installsAfter": ["ghcr.io/devcontainers/features/common-utils"]

package/features/cross-distro-packages/install.sh

@@ -14,6 +14,50 @@ deduplicate_packages() {
     echo "$packages" | tr ' ' '\n' | sort -u | tr '\n' ' ' | sed 's/ $//'
 }
 
+resolve_package_token() {
+    local manager="$1"
+    local token="$2"
+    local IFS='|'
+    read -r -a candidates <<< "$token"
+
+    for candidate in "${candidates[@]}"; do
+        if [ -z "$candidate" ]; then
+            continue
+        fi
+
+        if [ "$manager" = "apt" ]; then
+            if apt-cache show "$candidate" >/dev/null 2>&1; then
+                echo "$candidate"
+                return 0
+            fi
+        elif [ "$manager" = "apk" ]; then
+            if apk search -x "$candidate" >/dev/null 2>&1; then
+                echo "$candidate"
+                return 0
+            fi
+        fi
+    done
+
+    return 1
+}
+
+resolve_package_list() {
+    local manager="$1"
+    local packages="$2"
+    local resolved=()
+
+    for token in $packages; do
+        local selected=""
+        if ! selected=$(resolve_package_token "$manager" "$token"); then
+            echo "❌ No package candidate found for \"$token\" using $manager" >&2
+            exit 1
+        fi
+        resolved+=("$selected")
+    done
+
+    deduplicate_packages "${resolved[*]}"
+}
+
 # Exit early if no packages specified
 if [ -z "$APT_PACKAGES" ] && [ -z "$APK_PACKAGES" ]; then
     echo "⚠️  No packages specified for installation"
@@ -26,9 +70,8 @@ echo "📦 Installing cross-distro packages..."
 if command -v apk > /dev/null 2>&1; then
     # Alpine Linux (apk)
     if [ -n "$APK_PACKAGES" ]; then
-        # Deduplicate package list
-        APK_PACKAGES=$(deduplicate_packages "$APK_PACKAGES")
-        
+        APK_PACKAGES=$(resolve_package_list "apk" "$APK_PACKAGES")
+
         echo "  Detected: Alpine Linux (apk)"
         echo "  Installing: $APK_PACKAGES"
         apk add --no-cache $APK_PACKAGES
@@ -39,12 +82,11 @@ if command -v apk > /dev/null 2>&1; then
 elif command -v apt-get > /dev/null 2>&1; then
     # Debian/Ubuntu (apt)
     if [ -n "$APT_PACKAGES" ]; then
-        # Deduplicate package list
-        APT_PACKAGES=$(deduplicate_packages "$APT_PACKAGES")
-        
+        apt-get update
+        APT_PACKAGES=$(resolve_package_list "apt" "$APT_PACKAGES")
+
         echo "  Detected: Debian/Ubuntu (apt)"
         echo "  Installing: $APT_PACKAGES"
-        apt-get update
         DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends $APT_PACKAGES
         apt-get clean
         rm -rf /var/lib/apt/lists/*