container-superposition 0.1.4 → 0.1.6

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"

package/overlays/opencode/README.md

@@ -0,0 +1,76 @@
+# opencode Overlay
+
+Adds the `opencode` AI coding agent for terminal-based development assistance.
+
+## Features
+
+- **opencode CLI** — Multi-provider AI coding agent for the terminal
+- **Provider flexibility** — Supports multiple AI providers (OpenAI, Anthropic, Google, and more)
+
+## What is opencode?
+
+opencode is an open-source, terminal-based AI coding agent that supports multiple AI providers:
+
+- **Multi-provider** — Choose from OpenAI, Anthropic, Google Gemini, and other providers
+- **Code generation** — Generate new code from natural language descriptions
+- **Codebase context** — Understands your project structure
+- **Agentic tasks** — Execute multi-step coding tasks autonomously
+
+## How It Works
+
+This overlay installs `opencode-ai` globally via npm, making the `opencode` command available in your devcontainer.
+
+## Common Commands
+
+```bash
+# Start an interactive session
+opencode
+
+# Check version
+opencode --version
+```
+
+## Use Cases
+
+- **Flexible AI assistant** — Switch between AI providers as needed
+- **Open-source first** — Works with self-hosted models via compatible APIs
+- **Spec-Driven Development** — Works with `spec-kit` overlay via `specify init --ai opencode`
+
+**Integrates well with:**
+
+- `spec-kit` — Use opencode with the SDD workflow
+- `nodejs` — Required for installation
+- `git-helpers` — Git integration for AI-generated code
+
+## Configuration
+
+Configure your AI provider API key:
+
+```bash
+# For OpenAI
+export OPENAI_API_KEY=your-key
+
+# For Anthropic
+export ANTHROPIC_API_KEY=your-key
+
+# For Google Gemini
+export GEMINI_API_KEY=your-key
+```
+
+## Verification
+
+```bash
+bash .devcontainer/scripts/verify-opencode.sh
+```
+
+## References
+
+- [opencode Website](https://opencode.ai)
+- [opencode GitHub](https://github.com/sst/opencode)
+
+**Related Overlays:**
+
+- `spec-kit` — Spec-Driven Development with opencode 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/opencode/devcontainer.patch.json

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

package/overlays/opencode/overlay.yml

@@ -0,0 +1,14 @@
+id: opencode
+name: opencode
+description: opencode AI coding agent for terminal-based development assistance
+category: dev
+supports: []
+requires:
+    - nodejs
+suggests: []
+conflicts: []
+tags:
+    - dev
+    - ai
+    - opencode
+ports: []

package/overlays/opencode/setup.sh

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

package/overlays/opencode/verify.sh

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