container-superposition 0.1.4 → 0.1.5

package/docs/workflows.md

@@ -0,0 +1,136 @@
+# Workflows and Regeneration
+
+This guide covers project-config driven generation, manifest-based regeneration,
+and common workflows.
+
+## Project Config Workflow
+
+Commit exactly one project config file at the repository root:
+
+- `.superposition.yml`
+- `superposition.yml`
+
+Use it when you want standard `init` runs to start from committed defaults
+instead of a copied command line.
+
+```bash
+npx container-superposition init
+```
+
+Use `--no-interactive` when the config fully describes the intended setup and
+you want unattended generation:
+
+```bash
+npx container-superposition init --no-interactive
+```
+
+Direct CLI flags still win for that run only:
+
+```bash
+npx container-superposition init --no-interactive --output ./tmp-devcontainer
+```
+
+## Manifest Basics
+
+Every generation writes a `superposition.json` manifest that records your choices. It enables:
+
+- Reproducible environments
+- Safe upgrades
+- Team sharing
+- Regeneration with backups
+
+## When to Regenerate
+
+Use `regen` when you:
+
+- Add or remove overlays
+- Update to newer overlay versions
+- Change port offsets
+- Switch base templates
+
+Use `init --from-project` or `init --from-manifest` when you:
+
+- Want to start from a persisted source and then adjust choices interactively
+- Want a persisted source to provide defaults before making a targeted change
+
+Use manual edits when you:
+
+- Adjust VS Code settings
+- Add small scripts or config files
+- Tweak a single setting in custom patches
+
+## Quick Regeneration
+
+```bash
+# Uses the repository project file when one exists
+npx container-superposition regen
+
+# Or select the project file explicitly
+npx container-superposition regen --from-project
+
+# Falls back to manifest discovery when no project file exists
+npx container-superposition regen
+```
+
+## Regeneration With Changes
+
+```bash
+# Uses manifest as defaults, then prompts for changes
+npx container-superposition init --from-manifest ./.devcontainer/superposition.json
+
+# Uses the repository project file as defaults, then prompts for changes
+npx container-superposition init --from-project
+```
+
+## Source-Selection Conflicts
+
+Persisted-input source flags are mutually exclusive and do not mix with
+clean-generation selection flags:
+
+```bash
+# Invalid: two persisted sources
+npx container-superposition regen --from-project --from-manifest ./.devcontainer/superposition.json
+
+# Invalid: persisted source plus structural selection flags
+npx container-superposition init --from-project --stack compose
+```
+
+## Non-Interactive (CI/CD)
+
+```bash
+npx container-superposition init --no-interactive
+
+# Or keep using an explicit manifest when you want that mode
+npx container-superposition init \
+  --from-manifest ./.devcontainer/superposition.json \
+  --no-interactive \
+  --no-backup
+```
+
+## Backup Behavior
+
+- Default: creates `.devcontainer.backup-<timestamp>/`
+- `--no-backup`: skips backup
+- `--backup-dir <path>`: writes backups to a custom location
+
+## Example Workflow
+
+```bash
+# 1. Initial setup
+npx container-superposition init --stack compose --language nodejs --database postgres
+
+# 2. Later: reapply the committed project file
+npx container-superposition regen
+
+# 3. Or regenerate explicitly from a manifest when that is the intended source
+npx container-superposition init --from-manifest ./.devcontainer/superposition.json
+
+# 4. Update to latest overlays
+npx container-superposition@latest regen
+```
+
+## Team Workflow
+
+For a manifest-first approach (commit only `superposition.json`), see:
+
+- [team-workflow.md](team-workflow.md)

package/overlays/.presets/sdd.yml

@@ -0,0 +1,84 @@
+# Spec-Driven Development Preset
+# Complete environment for SDD with specify-cli and your choice of AI coding agent
+
+id: sdd
+name: Spec-Driven Development
+description: Complete Spec-Driven Development environment with specify-cli and your choice of AI coding agent
+type: meta
+category: preset
+supports: []
+tags: [preset, sdd, spec-driven, ai, specify, spec-kit]
+
+# Overlays to always include
+selects:
+    required:
+        - spec-kit
+
+# Parameterized agent selection
+# Option 'id' is the value passed to `specify init --ai <id>`.
+# 'overlays' is the list of container-superposition overlay IDs to include.
+parameters:
+    agent:
+        description: AI coding agent to use with Spec Kit
+        default: codex
+        options:
+            - id: codex
+              overlays: [codex]
+              description: OpenAI Codex CLI (--ai codex)
+            - id: claude
+              overlays: [claude-code]
+              description: Anthropic Claude Code (--ai claude)
+            - id: gemini
+              overlays: [gemini-cli]
+              description: Google Gemini CLI (--ai gemini)
+            - id: amp
+              overlays: [amp]
+              description: Sourcegraph Amp (--ai amp)
+            - id: windsurf
+              overlays: [windsurf-cli]
+              description: Codeium Windsurf (--ai windsurf)
+            - id: opencode
+              overlays: [opencode]
+              description: opencode (--ai opencode)
+            - id: copilot
+              overlays: []
+              description: GitHub Copilot (IDE-integrated, no extra CLI needed) (--ai copilot)
+
+# Glue configuration
+glueConfig:
+    # environment values support {{parameters.<key>.id}} template substitution —
+    # the preset expander replaces it with the selected option's id at generation time.
+    environment:
+        SPECIFY_AI_AGENT: '{{parameters.agent.id}}'
+
+    readme: |
+        ## Spec-Driven Development (SDD)
+
+        This devcontainer is configured for Spec-Driven Development using [Spec Kit](https://github.com/github/spec-kit).
+
+        ### Getting Started
+
+        Initialize SDD in your project:
+
+        ```bash
+        specify init . --here --ai ${SPECIFY_AI_AGENT:-codex}
+        ```
+
+        ### SDD Workflow
+
+        Use these slash commands in your AI agent:
+
+        | Step | Command | Description |
+        |------|---------|-------------|
+        | 1 | `/speckit.constitution` | Create project governing principles |
+        | 2 | `/speckit.specify` | Define requirements |
+        | 3 | `/speckit.clarify` | Clarify ambiguities |
+        | 4 | `/speckit.plan` | Create implementation plan |
+        | 5 | `/speckit.analyze` | Cross-artifact consistency check |
+        | 6 | `/speckit.tasks` | Break plan into tasks |
+        | 7 | `/speckit.implement` | Execute tasks with AI |
+
+        ### References
+
+        - [Spec Kit GitHub](https://github.com/github/spec-kit)
+        - [SDD Methodology](https://github.com/github/spec-kit/blob/main/spec-driven.md)

package/overlays/README.md

@@ -55,7 +55,13 @@ Each overlay directory contains:
 - **docker-in-docker** - Docker daemon inside container (conflicts with docker-sock)
 - **docker-sock** - Docker socket mounting (conflicts with docker-in-docker)
 - **playwright** - Browser automation with Chromium installed
-- **codex** - AI-powered code assistant
+- **codex** - OpenAI Codex CLI for AI-powered code generation and assistance
+- **spec-kit** - Specify CLI for Spec-Driven Development with any AI coding agent
+- **claude-code** - Anthropic Claude Code CLI for AI-powered development assistance
+- **gemini-cli** - Google Gemini CLI for AI-powered development assistance
+- **amp** - Sourcegraph Amp CLI for AI-powered code generation and assistance
+- **windsurf-cli** - Codeium Windsurf CLI for AI-powered development assistance
+- **opencode** - opencode AI coding agent for terminal-based development assistance
 
 ## Environment Variables
 

package/overlays/amp/README.md

@@ -0,0 +1,70 @@
+# Amp Overlay
+
+Adds the Sourcegraph Amp CLI (`amp`) for AI-powered code generation and development assistance.
+
+## Features
+
+- **Amp CLI** — Sourcegraph's AI coding agent for the terminal
+- **Codebase-aware** — Understands your entire repository context
+
+## What is Amp?
+
+Amp is Sourcegraph's AI coding agent that works directly in your terminal with deep codebase understanding:
+
+- **Code generation** — Generate new features from natural language
+- **Codebase context** — Indexed understanding of your entire codebase
+- **Multi-file edits** — Make consistent changes across the project
+- **Task execution** — Autonomous multi-step development tasks
+
+## How It Works
+
+This overlay installs `@sourcegraph/amp` globally via npm, making the `amp` command available in your devcontainer.
+
+## Common Commands
+
+```bash
+# Start an interactive session
+amp
+
+# Check version
+amp --version
+```
+
+## Use Cases
+
+- **Feature development** — Describe features, Amp implements them across the codebase
+- **Large refactors** — Make consistent changes across many files
+- **Code review** — AI-assisted code analysis
+- **Spec-Driven Development** — Works with `spec-kit` overlay via `specify init --ai amp`
+
+**Integrates well with:**
+
+- `spec-kit` — Use Amp with the SDD workflow
+- `nodejs` — Required for installation
+- `git-helpers` — Git integration for AI-generated code
+
+## Configuration
+
+Authenticate with your Sourcegraph account:
+
+```bash
+amp auth
+```
+
+## Verification
+
+```bash
+bash .devcontainer/scripts/verify-amp.sh
+```
+
+## References
+
+- [Amp by Sourcegraph](https://sourcegraph.com/amp)
+- [Sourcegraph Platform](https://sourcegraph.com/)
+
+**Related Overlays:**
+
+- `spec-kit` — Spec-Driven Development with Amp 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/amp/devcontainer.patch.json

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

package/overlays/amp/overlay.yml

@@ -0,0 +1,15 @@
+id: amp
+name: Amp
+description: Sourcegraph Amp CLI for AI-powered code generation and assistance
+category: dev
+supports: []
+requires:
+    - nodejs
+suggests: []
+conflicts: []
+tags:
+    - dev
+    - ai
+    - amp
+    - sourcegraph
+ports: []

package/overlays/amp/setup.sh

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

package/overlays/amp/verify.sh

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

package/overlays/claude-code/README.md

@@ -0,0 +1,83 @@
+# Claude Code Overlay
+
+Adds the Anthropic Claude Code CLI (`claude`) for AI-powered development assistance directly in the terminal.
+
+## Features
+
+- **Claude Code CLI** — Interactive AI coding assistant from Anthropic
+- **Terminal-first workflow** — Agentic coding directly from the command line
+
+## What is Claude Code?
+
+Claude Code is Anthropic's agentic coding tool that lives in the terminal. It understands your codebase and helps you code faster through natural conversation and autonomous task execution:
+
+- **Code generation** — Generate new features and components
+- **Code review** — Get feedback on your code
+- **Debugging** — Identify and fix issues
+- **Refactoring** — Improve existing code
+- **Testing** — Write and run tests
+
+## How It Works
+
+This overlay installs `@anthropic-ai/claude-code` globally via npm, making the `claude` command available in your devcontainer.
+
+## Common Commands
+
+```bash
+# Start an interactive session
+claude
+
+# Ask a one-off question
+claude "explain this function"
+
+# Authenticate with your Anthropic account
+claude auth
+
+# Check current version
+claude --version
+```
+
+## Use Cases
+
+- **Feature development** — Describe what you want to build, Claude implements it
+- **Code review** — Get AI feedback on pull requests or code changes
+- **Learning** — Understand unfamiliar codebases or concepts
+- **Refactoring** — Improve code quality with AI assistance
+- **Spec-Driven Development** — Works with the `spec-kit` overlay via `specify init --ai claude`
+
+**Integrates well with:**
+
+- `spec-kit` — Use Claude Code with the SDD workflow
+- `nodejs` — Required for installation
+- `git-helpers` — Git integration for AI-generated code
+- `pre-commit` — Quality gates for AI-generated code
+
+## Configuration
+
+Authentication is managed via the Anthropic API key:
+
+```bash
+# Set your API key
+export ANTHROPIC_API_KEY=your-api-key
+
+# Or authenticate interactively
+claude auth
+```
+
+## Verification
+
+```bash
+bash .devcontainer/scripts/verify-claude-code.sh
+```
+
+## References
+
+- [Claude Code Documentation](https://docs.anthropic.com/en/docs/claude-code)
+- [Anthropic Platform](https://console.anthropic.com/)
+
+**Related Overlays:**
+
+- `spec-kit` — Spec-Driven Development with Claude as the AI agent
+- `codex` — OpenAI Codex CLI (alternative AI assistant)
+- `gemini-cli` — Google Gemini CLI (alternative AI assistant)
+- `nodejs` — Required for npm-based installation

package/overlays/claude-code/devcontainer.patch.json

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

package/overlays/claude-code/overlay.yml

@@ -0,0 +1,15 @@
+id: claude-code
+name: Claude Code
+description: Anthropic Claude Code CLI for AI-powered development assistance
+category: dev
+supports: []
+requires:
+    - nodejs
+suggests: []
+conflicts: []
+tags:
+    - dev
+    - ai
+    - claude
+    - anthropic
+ports: []

package/overlays/claude-code/setup.sh

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

package/overlays/claude-code/verify.sh

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

package/overlays/gemini-cli/README.md

@@ -0,0 +1,77 @@
+# Gemini CLI Overlay
+
+Adds the Google Gemini CLI (`gemini`) for AI-powered development assistance directly in the terminal.
+
+## Features
+
+- **Gemini CLI** — Google's AI-powered coding assistant for the terminal
+- **Gemini 2.0 Flash** — Free tier available with Google account
+
+## What is Gemini CLI?
+
+The Google Gemini CLI is an open-source AI agent that brings Google's Gemini models directly to your terminal workflow:
+
+- **Code generation** — Generate code from natural language descriptions
+- **Codebase queries** — Ask questions about your code
+- **Agentic tasks** — Execute multi-step coding tasks autonomously
+- **Web grounding** — Access Google Search for up-to-date information
+
+## How It Works
+
+This overlay installs `@google/gemini-cli` globally via npm, making the `gemini` command available in your devcontainer.
+
+## Common Commands
+
+```bash
+# Start an interactive session
+gemini
+
+# Ask a one-off question
+gemini "how do I implement a binary search tree in TypeScript?"
+
+# Check version
+gemini --version
+```
+
+## Use Cases
+
+- **Code generation** — Describe features, Gemini implements them
+- **Codebase exploration** — Understand large or unfamiliar codebases
+- **Debugging** — Diagnose and fix errors with AI help
+- **Spec-Driven Development** — Works with `spec-kit` overlay via `specify init --ai gemini`
+
+**Integrates well with:**
+
+- `spec-kit` — Use Gemini CLI with the SDD workflow
+- `nodejs` — Required for installation
+- `git-helpers` — Git integration for AI-generated code
+
+## Configuration
+
+Authenticate using your Google account or a Gemini API key:
+
+```bash
+# Interactive authentication (opens browser)
+gemini auth
+
+# Or set API key
+export GEMINI_API_KEY=your-api-key
+```
+
+## Verification
+
+```bash
+bash .devcontainer/scripts/verify-gemini-cli.sh
+```
+
+## References
+
+- [Gemini CLI GitHub](https://github.com/google-gemini/gemini-cli)
+- [Google AI Studio](https://aistudio.google.com/)
+
+**Related Overlays:**
+
+- `spec-kit` — Spec-Driven Development with Gemini 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/gemini-cli/devcontainer.patch.json

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

package/overlays/gemini-cli/overlay.yml

@@ -0,0 +1,15 @@
+id: gemini-cli
+name: Gemini CLI
+description: Google Gemini CLI for AI-powered development assistance
+category: dev
+supports: []
+requires:
+    - nodejs
+suggests: []
+conflicts: []
+tags:
+    - dev
+    - ai
+    - gemini
+    - google
+ports: []

package/overlays/gemini-cli/setup.sh

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

package/overlays/gemini-cli/verify.sh

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