add-dev-environment-setup

name	add-dev-environment-setup
description	Use when bash/git/jq/gh CLI are missing or VS Code terminal is not WSL — detects OS, diagnoses gaps, installs missing tools.

Dev Environment Setup

Overview

Detect OS → diagnose silently → confirm → install → configure VS Code. Never assume what's installed. Never install without confirmation. Never overwrite settings.json.

---

When to Use

• User asks about environment setup or "how do I run the scripts"
• bash, git, jq, or gh not found
• status.sh fails due to missing tool
• VS Code terminal opens PowerShell/Git Bash instead of WSL

When NOT to Use

• All tools already installed and verified
• User is on Linux with working environment
• Container or CI environment (ephemeral; tools provisioned by image/workflow)

---

⛔ ABSOLUTE PROHIBITIONS

⛔ NEVER use Bash tool for sudo/apt/dnf/pacman/brew/curl|bash/wsl --install/gh auth login (hangs on password or interactive prompt)
⛔ NEVER overwrite .vscode/settings.json, reinstall WSL when a real distro exists, suggest Git Bash, use `apt-get install gh`, or proceed after user says N
✅ ALWAYS show install commands in code blocks → user runs manually → verify with non-sudo `--version` checks

---

STEP 1: DETECT OS (MANDATORY FIRST)

uname -s          # macOS → Darwin | Linux → Linux
$env:OS           # Windows PowerShell → Windows_NT

⛔ DO NOT proceed without TARGET_OS = windows | macos | linux.

---

STEP 2: DIAGNOSE (silent — no prompts yet)

Tool	Check	Windows note
WSL	wsl -l -v	docker-desktop only = NOT ready
bash	bash --version	Must be inside WSL, not Git Bash
git	git --version	Inside WSL
gh	gh --version	Inside WSL

WSL check logic:

• wsl -l -v shows a real distro (Ubuntu, Debian, etc.) → WSL is ready, use existing distro
• wsl -l -v shows only docker-desktop or nothing → WSL NOT ready, install Debian ⛔ DO NOT reinstall WSL if a real distro already exists — use whatever is installed.

---

STEP 3: REPORT

Show what is missing vs already installed:

✅ WSL2: Debian installed
❌ git: not found inside WSL
✅ gh: installed

---

STEP 4: CONFIRM

SAY: "I'll show you the commands to install. You run them in the terminal and let me know when you're done."

⛔ IF user says N → STOP.

Windows only — admin check: ⛔ IF wsl --install is needed → SAY first: "To install WSL you need a terminal with Administrator privileges. Open PowerShell as Administrator and run the command I'll show you." ⛔ DO NOT USE Bash tool to run wsl --install.

---

STEP 5: INSTRUCT USER TO INSTALL

⛔ DO NOT USE Bash tool for ANY command in this step. ⛔ ALL commands below are SHOWN to the user in code blocks — user copies and runs manually. ⛔ AFTER each sub-step, WAIT for user confirmation before proceeding to the next. ✅ AFTER user confirms execution → proceed to STEP 6 (VERIFY) using non-sudo checks.

Windows

5.1 — WSL2 + Debian (only if no real distro found in STEP 2) ⛔ IF user already has Ubuntu, Debian, or any real distro → SKIP this step, use existing distro.

SAY: "Run in PowerShell as Administrator:"

wsl --install -d Debian

SAY: "Restart Windows. Open the Debian terminal to complete the setup and let me know."

5.2 — Tools inside WSL

SAY: "Run in the WSL terminal:"

sudo apt update && sudo apt install -y git curl

5.3 — gh CLI (official repo — NOT apt-get install gh)

SAY: "Run these commands in the WSL terminal, one block at a time:"

curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg \
  | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg
sudo chmod go+r /usr/share/keyrings/githubcli-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] \
  https://cli.github.com/packages stable main" \
  | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null
sudo apt update && sudo apt install -y gh

5.4 — gh auth login

SAY: "Run in the WSL terminal:"

gh auth login

SAY: "Select: GitHub.com → HTTPS → Login with a web browser. Paste the code in the browser."

5.5 — VS Code settings.json (mandatory)

READ .vscode/settings.json. MERGE WSL profile. WRITE back. ⛔ DO NOT overwrite — preserve all existing profiles (Git Bash, PowerShell, Cmder, etc.).

Use the distro name detected in STEP 2 (e.g., Debian, Ubuntu, Ubuntu-24.04):

{
  "terminal.integrated.defaultProfile.windows": "WSL",
  "terminal.integrated.profiles.windows": {
    "WSL": {
      "path": "C:\\WINDOWS\\System32\\wsl.exe",
      "args": ["-d", "<DETECTED_DISTRO>"],
      "icon": "terminal-linux"
    }
  }
}

Result: user opens VS Code normally (shortcut/taskbar/recent files) → new terminal opens WSL automatically. No workflow change needed.

---

Unix (macOS + Linux)

⛔ DO NOT USE Bash tool. SHOW all commands to user.

Pick the package manager that matches the user's OS:

OS	Install command
macOS (Homebrew)	brew install git gh (install Homebrew first if missing — see below)
Debian/Ubuntu	sudo apt update && sudo apt install -y git curl then official gh repo (same flow as Windows 5.3)
Fedora/RHEL	sudo dnf install -y git gh
Arch	sudo pacman -S git github-cli

SAY: "Run in the terminal:"

# macOS — install Homebrew if missing
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# macOS — bash upgrade if < 4.0
bash --version
brew install bash   # if needed

After install, in all cases:

gh auth login

---

STEP 6: VERIFY

✅ This step CAN use Bash tool — verification commands are non-sudo, non-interactive.

git --version && gh --version && echo "✅ All tools ready"

⛔ IF any tool still missing → diagnose installation error. DO NOT declare success.

---

Common Mistakes

Mistake	Fix
wsl --install without admin	Confirm admin first → "Run as Administrator"
sudo apt-get install gh	Use official gh CLI repo — apt version is outdated
wsl -l -v shows only docker-desktop or empty	Install Debian: wsl --install -d Debian
Ubuntu already installed	Use it — do NOT reinstall with Debian
Overwriting settings.json	Always READ → MERGE → WRITE
Suggesting Git Bash as bash	Git Bash is NOT supported — WSL only
Skipping settings.json	It's mandatory — user won't change VS Code workflow
Proceeding after user says N	Stop immediately, show manual commands only
Declaring success before verifying	Run STEP 6 first
Running sudo/apt/brew via Bash tool	Agent hangs — sudo requires password. SHOW commands, user runs manually
Running gh auth login via Bash tool	Agent hangs — interactive prompt. SHOW command, guide user step by step
Running curl | bash via Bash tool	Agent hangs — interactive installer. SHOW command, user runs manually