diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json new file mode 100644 index 000000000..2b57f67e9 --- /dev/null +++ b/.devcontainer/devcontainer.json @@ -0,0 +1,58 @@ +// For format details, see https://aka.ms/devcontainer.json. For config options, see the +// README at: https://github.com/devcontainers/templates/tree/main/src/python +{ + "name": "SpecKitDevContainer", + // Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile + "image": "mcr.microsoft.com/devcontainers/python:3.13-trixie", // based on Debian "Trixie" (13) + "features": { + "ghcr.io/devcontainers/features/common-utils:2": { + "installZsh": true, + "installOhMyZsh": true, + "installOhMyZshConfig": true, + "upgradePackages": true, + "username": "devcontainer", + "userUid": "automatic", + "userGid": "automatic" + }, + "ghcr.io/devcontainers/features/dotnet:2": { + "version": "lts" + }, + "ghcr.io/devcontainers/features/git:1": { + "ppa": true, + "version": "latest" + } + }, + + // Use 'forwardPorts' to make a list of ports inside the container available locally. + "forwardPorts": [ + 8080 // for Spec-Kit documentation site + ], + "containerUser": "devcontainer", + "updateRemoteUserUID": true, + "postCreateCommand": "chmod +x ./.devcontainer/post-create.sh && ./.devcontainer/post-create.sh", + "postStartCommand": "git config --global --add safe.directory ${containerWorkspaceFolder}", + "customizations": { + "vscode": { + "extensions": [ + "mhutchie.git-graph", + "eamodio.gitlens", + "anweber.reveal-button", + "chrisdias.promptboost", + // Github Copilot + "GitHub.copilot", + "GitHub.copilot-chat", + // Codex + "openai.chatgpt", + // Kilo Code + "kilocode.Kilo-Code", + // Roo Code + "RooVeterinaryInc.roo-cline", + // Amazon Developer Q + "AmazonWebServices.amazon-q-vscode" + ], + "settings": { + "debug.javascript.autoAttachFilter": "disabled" // fix running commands in integrated terminal + } + } + } +} diff --git a/.devcontainer/post-create.sh b/.devcontainer/post-create.sh new file mode 100755 index 000000000..797fd831b --- /dev/null +++ b/.devcontainer/post-create.sh @@ -0,0 +1,85 @@ +#!/bin/bash + +# Exit immediately on error, treat unset variables as an error, and fail if any command in a pipeline fails. +set -euo pipefail + +# Function to run a command and show logs only on error +run_command() { + local command_to_run="$*" + local output + local exit_code + + # Capture all output (stdout and stderr) + output=$(eval "$command_to_run" 2>&1) || exit_code=$? + exit_code=${exit_code:-0} + + if [ $exit_code -ne 0 ]; then + echo -e "\033[0;31m[ERROR] Command failed (Exit Code $exit_code): $command_to_run\033[0m" >&2 + echo -e "\033[0;31m$output\033[0m" >&2 + + return $exit_code + fi +} + +# Note: We use Bun (instead of npm) as our package manager for its speed and overall efficiency +# It is a drop-in replacement for Node.js, so we can install npm packages through it without issues +echo "๐Ÿ“ฆ Installing Bun Package Manager..." +run_command "curl -fsSL https://bun.sh/install | bash" +run_command "source ~/.bashrc" +echo "โœ… Done" + +export BUN_INSTALL="$HOME/.bun" +export PATH="$BUN_INSTALL/bin:$PATH" + +# Installing CLI-based AI Agents + +echo -e "\n๐Ÿค– Installing Copilot CLI..." +run_command "bun add --global @github/copilot@latest" +echo "โœ… Done" + +echo -e "\n๐Ÿค– Installing Claude CLI..." +run_command "bun add --global @anthropic-ai/claude-code@latest" +echo "โœ… Done" + +echo -e "\n๐Ÿค– Installing Codex CLI..." +run_command "bun add --global @openai/codex@latest" +echo "โœ… Done" + +echo -e "\n๐Ÿค– Installing Gemini CLI..." +run_command "bun add --global @google/gemini-cli@latest" +echo "โœ… Done" + +echo -e "\n๐Ÿค– Installing Augie CLI..." +run_command "bun add --global @augmentcode/auggie@latest" +echo "โœ… Done" + +echo -e "\n๐Ÿค– Installing Qwen Code CLI..." +run_command "bun add --global @qwen-code/qwen-code@latest" +echo "โœ… Done" + +echo -e "\n๐Ÿค– Installing OpenCode CLI..." +run_command "bun add --global opencode-ai@latest" +echo "โœ… Done" + +echo -e "\n๐Ÿค– Installing Amazon Developer Q CLI..." +run_command "curl --proto '=https' --tlsv1.2 -sSf \"https://desktop-release.q.us-east-1.amazonaws.com/latest/q-x86_64-linux.zip\" -o \"q.zip\"" +run_command "unzip q.zip && rm q.zip" +run_command "./q/install.sh --no-confirm" +run_command "rm -rf ./q" +echo "โœ… Done" + +# Installing UV (Python package manager) +echo -e "\n๐Ÿ Installing UV - Python Package Manager..." +run_command "pipx install uv" +echo "โœ… Done" + +# Installing DocFx (for documentation site) +echo -e "\n๐Ÿ“š Installing DocFx..." +run_command "dotnet tool update -g docfx" +echo "โœ… Done" + +echo -e "\n๐Ÿงน Cleaning cache..." +run_command "sudo apt-get autoclean" +run_command "sudo apt-get clean" + +echo "โœ… Setup completed. Happy coding! ๐Ÿš€" diff --git a/AGENTS.md b/AGENTS.md index 6cae67031..f4049c6f3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -192,6 +192,51 @@ elif selected_ai == "windsurf": **Note**: Skip CLI checks for IDE-based agents (Copilot, Windsurf). +#### 7. Update Devcontainer files (Optional) + +For agents that have VS Code extensions or require CLI installation, update the devcontainer configuration files: + +##### VS Code Extension-based Agents + +For agents available as VS Code extensions, add them to `.devcontainer/devcontainer.json`: + +```json +{ + "customizations": { + "vscode": { + "extensions": [ + // ... existing extensions ... + // [New Agent Name] + "[New Agent Extension ID]" + ] + } + } +} +``` + +##### CLI-based Agents + +For agents that require CLI tools, add installation commands to `.devcontainer/post-create.sh`: + +```bash +#!/bin/bash + +# Existing installations... + +echo -e "\n๐Ÿค– Installing [New Agent Name] CLI..." +# run_command "bun add --global [agent-cli-package]@latest" # Example for node-based CLI +# or other installation instructions (must be non-interactive and compatible with Linux Debian "Trixie" or later)... +echo "โœ… Done" + +``` + +**Quick Tips:** + +- **Extension-based agents**: Add to the `extensions` array in `devcontainer.json` +- **CLI-based agents**: Add installation scripts to `post-create.sh` +- **Hybrid agents**: May require both extension and CLI installation +- **Test thoroughly**: Ensure installations work in the devcontainer environment + ## Agent Categories ### CLI-Based Agents @@ -201,6 +246,7 @@ Require a command-line tool to be installed: - **Cursor**: `cursor-agent` CLI - **Qwen Code**: `qwen` CLI - **opencode**: `opencode` CLI +- **Amazon Q Developer CLI**: `q` CLI ### IDE-Based Agents Work within integrated development environments: diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bf65fa774..3aad86654 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -13,6 +13,23 @@ These are one time installations required to be able to test your changes locall 1. Install [Git](https://git-scm.com/downloads) 1. Have an [AI coding agent available](README.md#-supported-ai-agents) +
+๐Ÿ’ก Hint if you are using VSCode or Github Codespaces as your IDE + +
+ +Provided you have [Docker](https://docker.com) installed on your machine, you can leverage [Dev Containers](https://containers.dev) through this [VSCode extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers), to easily set up your development environment, with aforementioned tools already installed and configured, thanks to the `.devcontainer/devcontainer.json` file (located at the root of the project). + +To do so, simply: + +- Checkout the repo +- Open it with VSCode +- Open the [Command Palette](https://code.visualstudio.com/docs/getstarted/userinterface#_command-palette) and select "Dev Containers: Open Folder in Container..." + +On [Github Codespaces](https://github.com/features/codespaces) it's even simpler, as it leverages the `.devcontainer/devcontainer.json` automatically upon opening the codespace. + +
+ ## Submitting a pull request >[!NOTE]