diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json new file mode 100644 index 000000000..21091e749 --- /dev/null +++ b/.devcontainer/devcontainer.json @@ -0,0 +1,72 @@ +// 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 + + // Specify settings for Github Copilot + "git.autofetch": true, + "chat.promptFilesRecommendations": { + "speckit.constitution": true, + "speckit.specify": true, + "speckit.plan": true, + "speckit.tasks": true, + "speckit.implement": true + }, + "chat.tools.terminal.autoApprove": { + ".specify/scripts/bash/": true, + ".specify/scripts/ps/": true + } + } + } + } +} diff --git a/.devcontainer/post-create.sh b/.devcontainer/post-create.sh new file mode 100755 index 000000000..d66544953 --- /dev/null +++ b/.devcontainer/post-create.sh @@ -0,0 +1,106 @@ +#!/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 + + exit $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" +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 Q CLI..." +# ๐Ÿ‘‰๐Ÿพ https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/command-line-verify-download.html + +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 "curl --proto '=https' --tlsv1.2 -sSf 'https://desktop-release.q.us-east-1.amazonaws.com/latest/q-x86_64-linux.zip.sig' -o 'q.zip.sig'" +cat > amazonq-public-key.asc << 'EOF' +-----BEGIN PGP PUBLIC KEY BLOCK----- + +mDMEZig60RYJKwYBBAHaRw8BAQdAy/+G05U5/EOA72WlcD4WkYn5SInri8pc4Z6D +BKNNGOm0JEFtYXpvbiBRIENMSSBUZWFtIDxxLWNsaUBhbWF6b24uY29tPoiZBBMW +CgBBFiEEmvYEF+gnQskUPgPsUNx6jcJMVmcFAmYoOtECGwMFCQPCZwAFCwkIBwIC +IgIGFQoJCAsCBBYCAwECHgcCF4AACgkQUNx6jcJMVmef5QD/QWWEGG/cOnbDnp68 +SJXuFkwiNwlH2rPw9ZRIQMnfAS0A/0V6ZsGB4kOylBfc7CNfzRFGtovdBBgHqA6P +zQ/PNscGuDgEZig60RIKKwYBBAGXVQEFAQEHQC4qleONMBCq3+wJwbZSr0vbuRba +D1xr4wUPn4Avn4AnAwEIB4h+BBgWCgAmFiEEmvYEF+gnQskUPgPsUNx6jcJMVmcF +AmYoOtECGwwFCQPCZwAACgkQUNx6jcJMVmchMgEA6l3RveCM0YHAGQaSFMkguoAo +vK6FgOkDawgP0NPIP2oA/jIAO4gsAntuQgMOsPunEdDeji2t+AhV02+DQIsXZpoB +=f8yY +-----END PGP PUBLIC KEY BLOCK----- +EOF +run_command "gpg --batch --import amazonq-public-key.asc" +run_command "gpg --verify q.zip.sig q.zip" +run_command "unzip -q q.zip" +run_command "chmod +x ./q/install.sh" +run_command "./q/install.sh --no-confirm" +run_command "rm -rf ./q q.zip q.zip.sig amazonq-public-key.asc" +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..91c61243b 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]