From d63ffdf4c7b1a298b9d625ec4bd27a8acf260740 Mon Sep 17 00:00:00 2001 From: Tine Kondo Date: Mon, 22 Sep 2025 23:09:34 +0200 Subject: [PATCH 1/3] chore: add `devcontainer` support to ease developer workstation setup Fixes #466 --- .devcontainer/devcontainer.json | 58 ++++++++++++++++++++++ .devcontainer/post-create.sh | 85 +++++++++++++++++++++++++++++++++ AGENTS.md | 46 ++++++++++++++++++ CONTRIBUTING.md | 17 +++++++ 4 files changed, 206 insertions(+) create mode 100644 .devcontainer/devcontainer.json create mode 100755 .devcontainer/post-create.sh 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] From 7dffdd356493120b8423680d0fbad2c5ba43912d Mon Sep 17 00:00:00 2001 From: Tine Kondo Date: Wed, 8 Oct 2025 13:41:21 +0000 Subject: [PATCH 2/3] chore: add `specify`'s github copilot chat settings to `devcontainer` --- .devcontainer/devcontainer.json | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index 2b57f67e9..21091e749 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -51,7 +51,21 @@ "AmazonWebServices.amazon-q-vscode" ], "settings": { - "debug.javascript.autoAttachFilter": "disabled" // fix running commands in integrated terminal + "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 + } } } } From 7e23a86668d3fe6374420028e5a5cec3ca53c818 Mon Sep 17 00:00:00 2001 From: Tine Kondo Date: Wed, 8 Oct 2025 15:03:38 +0000 Subject: [PATCH 3/3] fix: correct `run_command` exit behavior and improve installation instructions (for `Amazon Q`) in `post-create.sh` + fix typos in `CONTRIBUTING.md` --- .devcontainer/post-create.sh | 33 +++++++++++++++++++++++++++------ CONTRIBUTING.md | 4 ++-- 2 files changed, 29 insertions(+), 8 deletions(-) diff --git a/.devcontainer/post-create.sh b/.devcontainer/post-create.sh index 797fd831b..d66544953 100755 --- a/.devcontainer/post-create.sh +++ b/.devcontainer/post-create.sh @@ -17,7 +17,7 @@ run_command() { 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 + exit $exit_code fi } @@ -25,7 +25,6 @@ run_command() { # 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" @@ -61,11 +60,33 @@ 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" + +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" +run_command "rm -rf ./q q.zip q.zip.sig amazonq-public-key.asc" echo "โœ… Done" # Installing UV (Python package manager) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3aad86654..91c61243b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -14,7 +14,7 @@ These are one time installations required to be able to test your changes locall 1. Have an [AI coding agent available](README.md#-supported-ai-agents)
-๐Ÿ’ก Hint if you are using VSCode or Github Codespaces as your IDE +๐Ÿ’ก Hint if you are using VSCode or GitHub Codespaces as your IDE
@@ -26,7 +26,7 @@ To do so, simply: - 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. +On [GitHub Codespaces](https://github.com/features/codespaces) it's even simpler, as it leverages the `.devcontainer/devcontainer.json` automatically upon opening the codespace.