Setup Vscode Swift

---
name: setup-vscode-swift
description: Inspect and configure VS Code for Swift and Xcode development on macOS. Use when installing SweetPad and the official Swift extension, configuring Cmd+R/Cmd+B shortcuts, installing xcode-build-server, creating buildServer.json, or diagnosing SourceKit-LSP completion. Trigger for requests such as "set up VS Code for iOS development," "configure SweetPad," "fix Swift autocomplete," or "create buildServer.json."
---

# VS Code Swift Setup

Inspect the Mac and target project first, then apply only the required changes. Use SweetPad and `xcode-build-server` for Xcode projects. Use SourceKit-LSP's built-in support for standalone Swift packages.

Treat the folder containing this document as the skill directory. Resolve the absolute path to `scripts/setup_vscode_swift.py` before running it. Do not assume a script with the same name exists in the user's current working directory.

## Workflow

1. Confirm that the target system is macOS.
2. Run `<skill-dir>/scripts/setup_vscode_swift.py doctor --project <project-root>`.
3. Briefly explain the installations and file changes required by the diagnosis.
4. Get approval for network downloads and user settings changes, then configure the global environment.
5. Apply project setup for an Xcode project.
6. Run `doctor` again and report any remaining manual steps.

## Global setup

Preview the change plan first.

```bash
python3 <skill-dir>/scripts/setup_vscode_swift.py global
```

Apply the changes after the user approves them.

```bash
python3 <skill-dir>/scripts/setup_vscode_swift.py global --apply
```

This command only performs the following actions:

- Install `sweetpad.sweetpad`, `swiftlang.swift-vscode`, and `vadimcn.vscode-lldb` in VS Code.
- Install `xcode-build-server` when Homebrew is available.
- Add `Cmd+R → sweetpad.build.launch` and `Cmd+B → sweetpad.build.build` to the user's VS Code shortcuts.
- Preserve the existing `keybindings.json` and back it up before making changes.

Do not install Homebrew or Xcode automatically. They may require large downloads, administrator privileges, an Apple account, or license acceptance. Ask the user to install them, then run the setup again.

## Project setup

Use the project root containing the `.xcworkspace` or `.xcodeproj`.

```bash
python3 <skill-dir>/scripts/setup_vscode_swift.py project <project-root>
python3 <skill-dir>/scripts/setup_vscode_swift.py project <project-root> --apply
```

Add `--scheme <name>` when the user specifies a scheme. Prefer a workspace when both a workspace and project exist at the root. If multiple containers of the same type exist, do not choose one automatically; use `--container <path>`.

Do not create `buildServer.json` for a standalone Swift package. Do not delete an existing file automatically; tell the user that it may interfere with SourceKit-LSP's built-in package support.

## Verification

Run the diagnosis again.

```bash
python3 <skill-dir>/scripts/setup_vscode_swift.py doctor --project <project-root>
```

Check the following:

- Xcode command line tools and Swift work correctly.
- All three VS Code extensions are installed.
- `xcode-build-server` is available.
- `buildServer.json` contains valid JSON.
- The SweetPad shortcuts are configured.

Code completion for Xcode projects needs a successful build log. After setup, tell the user to select a scheme and simulator in VS Code and build once with `Cmd+R`. SweetPad defaults `sweetpad.build.autoGenerateBuildServerConfig` and `sweetpad.build.autoRestartSwiftLSP` to `true`, so later builds and scheme changes automatically regenerate `buildServer.json` and restart Swift LSP. Only ask to re-enable these settings if the user has disabled them. If the issue remains, tell the user to run `SweetPad: Diagnose BSP (Doctor)` from the VS Code command palette.

## Safety rules

- Preview the plan without `--apply` first.
- Do not overwrite the user's complete settings file.
- When running with `--apply`, create a timestamped backup before replacing an existing `buildServer.json`.
- Do not change the selected Xcode version, accept licenses, or install Homebrew on the user's behalf.
- Do not continue without user input when multiple workspaces or projects exist.