container-superposition 0.1.3 → 0.1.5

package/overlays/spec-kit/setup.sh

@@ -0,0 +1,45 @@
+#!/bin/bash
+# spec-kit setup — install specify-cli for Spec-Driven Development
+
+set -e
+
+echo "📦 Installing prerequisites for spec-kit..."
+
+# Ensure uv tool bin directory is always on PATH (uv puts shims here regardless
+# of whether uv itself was pre-installed or freshly installed in this script)
+export PATH="$HOME/.local/bin:$PATH"
+
+# Ensure uv is available (fast Python package manager)
+if ! command -v uv &>/dev/null; then
+    echo "  Installing uv..."
+    curl -LsSf https://astral.sh/uv/install.sh | sh
+    # Re-source in case the installer wrote to a non-standard location
+    export PATH="$HOME/.cargo/bin:$HOME/.local/bin:$PATH"
+fi
+
+echo "📦 Installing specify-cli..."
+# Pin to a uv-managed Python (avoids broken system Python 3.13 on Debian trixie
+# where stdlib modules like shutil/os can be missing due to Debian's split packages)
+UV_PYTHON_VERSION="3.12"
+echo "  Ensuring uv-managed Python ${UV_PYTHON_VERSION} is available..."
+uv python install "${UV_PYTHON_VERSION}"
+
+# Install specify-cli using the uv-managed Python, not the system interpreter
+uv tool install specify-cli --from git+https://github.com/github/spec-kit.git \
+    --python "${UV_PYTHON_VERSION}"
+
+# Verify — use the full path as a fallback in case the shim dir is not yet in PATH
+SPECIFY_BIN="$(uv tool dir 2>/dev/null)/specify-cli/bin/specify"
+if command -v specify &>/dev/null; then
+    echo "✓ specify-cli installed: $(specify --version 2>/dev/null || echo 'ok')"
+elif [ -x "$SPECIFY_BIN" ]; then
+    echo "✓ specify-cli installed at $SPECIFY_BIN (add ~/.local/bin to PATH)"
+else
+    echo "✗ specify-cli installation failed"
+    exit 1
+fi
+
+echo "✓ spec-kit setup complete"
+echo "ℹ️  Spec Kit: https://github.com/github/spec-kit"
+echo "ℹ️  Usage:  specify init <PROJECT_NAME> --ai <agent>"
+echo "ℹ️  Agents: codex, claude, gemini, copilot, cursor-agent, windsurf, amp, ..."

package/overlays/spec-kit/verify.sh

@@ -0,0 +1,33 @@
+#!/bin/bash
+# spec-kit overlay verification script
+
+set -e
+
+# uv installs shims to ~/.local/bin; ensure it is on PATH
+export PATH="$HOME/.local/bin:$PATH"
+
+echo "🔍 Verifying spec-kit overlay setup..."
+
+# Check uv is available
+if ! command -v uv &>/dev/null; then
+    echo "✗ uv not found"
+    exit 1
+fi
+
+echo "✓ uv is installed: $(uv --version 2>/dev/null || echo 'installed')"
+
+# Check specify CLI is available
+if ! command -v specify &>/dev/null; then
+    echo "✗ specify not found"
+    exit 1
+fi
+
+echo "✓ specify is installed: $(specify --version 2>/dev/null || echo 'installed')"
+
+echo ""
+echo "✅ spec-kit overlay verification complete!"
+echo ""
+echo "💡 Tips:"
+echo "  - Run 'specify --help' to see available commands"
+echo "  - Initialize a project: specify init <PROJECT_NAME> --ai <agent>"
+echo "  - Supported agents: codex, claude, gemini, copilot, cursor-agent, windsurf, amp, ..."

package/overlays/windsurf-cli/README.md

@@ -0,0 +1,69 @@
+# Windsurf CLI Overlay
+
+Adds the Codeium Windsurf CLI (`windsurf`) for AI-powered development assistance in the terminal.
+
+## Features
+
+- **Windsurf CLI** — Codeium's AI coding agent for terminal use
+- **Cascade flows** — AI-driven multi-step development tasks
+
+## What is Windsurf CLI?
+
+Windsurf CLI is Codeium's headless agentic coding assistant that brings the power of the Windsurf IDE agent to the command line:
+
+- **Agentic coding** — Autonomous multi-step task execution
+- **Codebase understanding** — Deep indexing of your repository
+- **Code generation** — Create features from natural language
+- **Refactoring** — Improve existing code with AI guidance
+
+## How It Works
+
+This overlay installs the Windsurf CLI globally via npm, making the `windsurf` command available in your devcontainer.
+
+## Common Commands
+
+```bash
+# Start an interactive session
+windsurf
+
+# Check version
+windsurf --version
+```
+
+## Use Cases
+
+- **Feature implementation** — Describe what you want, Windsurf implements it
+- **Code exploration** — Understand large or complex codebases
+- **Spec-Driven Development** — Works with `spec-kit` overlay via `specify init --ai windsurf`
+
+**Integrates well with:**
+
+- `spec-kit` — Use Windsurf with the SDD workflow
+- `nodejs` — Required for installation
+- `git-helpers` — Git integration for AI-generated code
+
+## Configuration
+
+Authenticate with your Codeium account:
+
+```bash
+windsurf auth
+```
+
+## Verification
+
+```bash
+bash .devcontainer/scripts/verify-windsurf-cli.sh
+```
+
+## References
+
+- [Windsurf Documentation](https://docs.codeium.com/windsurf/getting-started)
+- [Codeium Platform](https://codeium.com/)
+
+**Related Overlays:**
+
+- `spec-kit` — Spec-Driven Development with Windsurf as the AI agent
+- `codex` — OpenAI Codex CLI (alternative AI assistant)
+- `claude-code` — Anthropic Claude Code (alternative AI assistant)
+- `nodejs` — Required for npm-based installation

package/overlays/windsurf-cli/devcontainer.patch.json

@@ -0,0 +1,3 @@
+{
+    "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json"
+}

package/overlays/windsurf-cli/overlay.yml

@@ -0,0 +1,15 @@
+id: windsurf-cli
+name: Windsurf CLI
+description: Codeium Windsurf CLI for AI-powered development assistance
+category: dev
+supports: []
+requires:
+    - nodejs
+suggests: []
+conflicts: []
+tags:
+    - dev
+    - ai
+    - windsurf
+    - codeium
+ports: []

package/overlays/windsurf-cli/setup.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+# windsurf-cli setup script - Install Codeium Windsurf CLI
+
+set -e
+
+echo "📦 Installing Codeium Windsurf CLI..."
+
+# Install windsurf globally via npm
+npm install -g @codeium/windsurf-cli
+
+# Verify installation
+if command -v windsurf &>/dev/null; then
+    echo "✓ Windsurf CLI installed successfully: $(windsurf --version 2>/dev/null || echo 'installed')"
+else
+    echo "✗ Windsurf CLI installation failed"
+    exit 1
+fi
+
+echo "✓ windsurf-cli setup complete"
+echo "ℹ️  Codeium Windsurf: https://docs.codeium.com/windsurf/getting-started"
+echo "ℹ️  Run 'windsurf --help' to get started"

package/overlays/windsurf-cli/verify.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+# windsurf-cli overlay verification script
+
+set -e
+
+echo "🔍 Verifying windsurf-cli overlay setup..."
+
+# Check if windsurf CLI is installed
+if ! command -v windsurf &>/dev/null; then
+    echo "✗ windsurf CLI is not installed or not in PATH"
+    exit 1
+fi
+
+echo "✓ windsurf CLI is installed: $(windsurf --version 2>/dev/null || echo 'installed')"
+
+echo ""
+echo "✅ windsurf-cli overlay verification complete!"
+echo ""
+echo "💡 Tips:"
+echo "  - Run 'windsurf --help' to see available commands"
+echo "  - Authenticate with your Codeium account"

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "container-superposition",
-    "version": "0.1.3",
+    "version": "0.1.5",
     "description": "Solution-ready devcontainer templates and features with guided initialization",
     "type": "module",
     "main": "dist/scripts/init.js",

package/tool/schema/config.schema.json

@@ -11,28 +11,67 @@
         },
         "baseImage": {
             "type": "string",
-            "enum": ["bookworm", "trixie", "custom"],
+            "enum": ["bookworm", "trixie", "alpine", "ubuntu", "custom"],
             "default": "bookworm",
-            "description": "Base Debian image version"
+            "description": "Base image / Linux distro variant (or 'custom' for a user-defined image)"
         },
         "customImage": {
             "type": "string",
             "description": "Custom base image (only when baseImage is 'custom')"
         },
+        "containerName": {
+            "type": "string",
+            "description": "Container/project name to write into devcontainer.json"
+        },
+        "preset": {
+            "type": "string",
+            "description": "Preset ID to expand during generation"
+        },
+        "presetChoices": {
+            "type": "object",
+            "additionalProperties": {
+                "type": "string"
+            },
+            "description": "Preset parameter choices keyed by parameter name"
+        },
         "language": {
             "type": "array",
             "items": {
                 "type": "string",
-                "enum": ["dotnet", "nodejs", "python", "mkdocs"]
+                "enum": [
+                    "dotnet",
+                    "nodejs",
+                    "python",
+                    "mkdocs",
+                    "java",
+                    "go",
+                    "rust",
+                    "bun",
+                    "powershell"
+                ]
             },
             "default": [],
             "description": "Language/framework overlays"
         },
         "database": {
-            "type": "string",
-            "enum": ["none", "postgres", "redis", "postgres+redis"],
-            "default": "none",
-            "description": "Database requirements"
+            "type": "array",
+            "items": {
+                "type": "string",
+                "enum": [
+                    "postgres",
+                    "redis",
+                    "mongodb",
+                    "mysql",
+                    "sqlserver",
+                    "sqlite",
+                    "minio",
+                    "rabbitmq",
+                    "redpanda",
+                    "nats"
+                ]
+            },
+            "default": [],
+            "description": "Database overlays"
         },
         "playwright": {
             "type": "boolean",
@@ -43,11 +82,38 @@
             "type": "array",
             "items": {
                 "type": "string",
-                "enum": ["azure-cli", "aws-cli", "kubectl-helm", "docker-in-docker", "docker-sock"]
+                "enum": ["azure-cli", "aws-cli", "gcloud", "kubectl-helm", "terraform", "pulumi"]
             },
             "default": [],
             "description": "Cloud/orchestration tools to include"
         },
+        "devTools": {
+            "type": "array",
+            "items": {
+                "type": "string",
+                "enum": [
+                    "docker-in-docker",
+                    "docker-sock",
+                    "codex",
+                    "playwright",
+                    "git-helpers",
+                    "pre-commit",
+                    "commitlint",
+                    "just",
+                    "direnv",
+                    "modern-cli-tools",
+                    "ngrok",
+                    "spec-kit",
+                    "claude-code",
+                    "gemini-cli",
+                    "amp",
+                    "windsurf-cli",
+                    "opencode"
+                ]
+            },
+            "default": [],
+            "description": "Developer tooling overlays"
+        },
         "observability": {
             "type": "array",
             "items": {
@@ -59,13 +125,76 @@
         },
         "portOffset": {
             "type": "number",
+            "minimum": 0,
             "description": "Port offset for running multiple instances"
         },
         "outputPath": {
             "type": "string",
             "default": "./.devcontainer",
             "description": "Where to write the devcontainer configuration"
+        },
+        "target": {
+            "type": "string",
+            "enum": ["local", "codespaces", "gitpod", "devpod"],
+            "description": "Target environment for compatibility checks"
+        },
+        "minimal": {
+            "type": "boolean",
+            "description": "Exclude optional overlays marked as minimal"
+        },
+        "editor": {
+            "type": "string",
+            "enum": ["vscode", "jetbrains", "none"],
+            "description": "Editor customization profile"
+        },
+        "customizations": {
+            "type": "object",
+            "properties": {
+                "devcontainerPatch": {
+                    "type": "object",
+                    "description": "Additional devcontainer.json content merged during generation"
+                },
+                "dockerComposePatch": {
+                    "type": "object",
+                    "description": "Additional docker-compose content merged during generation"
+                },
+                "environment": {
+                    "type": "object",
+                    "additionalProperties": {
+                        "type": "string"
+                    },
+                    "description": "Environment variables written to custom/environment.env"
+                },
+                "scripts": {
+                    "type": "object",
+                    "properties": {
+                        "postCreate": {
+                            "type": "array",
+                            "items": { "type": "string" }
+                        },
+                        "postStart": {
+                            "type": "array",
+                            "items": { "type": "string" }
+                        }
+                    },
+                    "additionalProperties": false
+                },
+                "files": {
+                    "type": "array",
+                    "items": {
+                        "type": "object",
+                        "properties": {
+                            "path": { "type": "string" },
+                            "content": { "type": "string" }
+                        },
+                        "required": ["path", "content"],
+                        "additionalProperties": false
+                    }
+                }
+            },
+            "additionalProperties": false
         }
     },
-    "required": ["stack"]
+    "required": [],
+    "additionalProperties": false
 }