[2026-10-15] eagle: work/projects/vscode-migration/tech-design-xcode-build-server.md

work/projects/vscode-migration/tech-design-xcode-build-server.md

@@ -8,7 +8,7 @@
 ## Background & Requirements
 
 - Some of us (would prefer to) spend much of the day outside Xcode: in VS Code, reviewing changes, working with AI agents, or across several worktrees at once. There, the Swift language server has no build information for our Xcode projects. So there's no direct build&run support, no jump to definition, no completion and no errors as you type, and no debugger.
-- The [previous tech design](https://app.asana.com/1/137249556945/project/1202406491309510/task/1219304032604521) tried to solve this by making the macOS browser code a Swift package. The team decided not to do it at this stage. The concerns were:
+- The [previous tech design](https://app.asana.com/1/137249556945/project/1202406491309510/task/1219304032604521) tried to solve this by making the macOS browser code a Swift package. The team has raised some concerns against doing it at this stage. The concerns were:
   - a more custom, more fragile setup;
   - resources that can fail silently at runtime;
   - no good way to have per-configuration dependencies;
@@ -41,14 +41,15 @@ Add an opt-in VS Code setup to the repository: a workspace file and a few script
 **How it works**
 - The workspace generates the build server's config on folder open. The config chooses the platform and the targets to index, the same way an Xcode scheme does.
 - Builds and tests go through `xcodebuild` with the same settings Xcode uses.
-- The build server is installed locally by a script, from a pinned version.
+- The build server is installed locally by a script that builds it from source at a pinned commit of our fork (see below).
 
-**The build server needed fixes.** On our workspace it gave no results in test files, broke on the DMG/App Store variants and took hours to index. Four small changes fix this (see Appendix), and a worktree now indexes in about 5 minutes. They're general improvements, so the plan is to contribute them upstream. Until they're merged, the repository carries them as a patch that the install script applies.
+**The build server needed fixes.** On our workspace it gave no results in test files, broke on the DMG/App Store variants and took hours to index. Four small changes fix this (see Appendix), and a worktree now indexes in about 5 minutes. They're general improvements, so we'll offer them upstream. We don't depend on upstream accepting them: we fork the build server into a DuckDuckGo repository, keep our changes there and pull upstream changes manually after reviewing them.
 
 **Steps**
-1. Land the setup in the repository, plus a short README.
-2. Open PRs for the build server changes in its repository.
-3. A few early adopters on macOS and iOS try it for a couple of weeks; then we decide whether to announce it more widely.
+1. Fork sourcekit-xcode-bsp into a DuckDuckGo repository with our changes.
+2. Land the setup in the repository, plus a short README.
+3. Offer the changes upstream as PRs.
+4. A few early adopters on macOS and iOS try it for a couple of weeks; then we decide whether to announce it more widely.
 
 ### Pros
 
@@ -60,17 +61,22 @@ Add an opt-in VS Code setup to the repository: a workspace file and a few script
 
 ### Cons
 
-- **A young third-party tool** (version 0.1.0, "early-stage" by its authors), and our patch on top of it until upstream accepts the changes.
+- **A young third-party tool** (version 0.1.0, "early-stage" by its authors) that we fork and maintain ourselves.
 - **Some rough edges:**
   - one platform per worktree at a time;
   - iOS debugging is two steps (run, then attach);
   - the first index of a new worktree takes ~5 minutes.
 - **Someone has to own it.** I will; the setup is small (a workspace file and ~6 scripts), and it's documented.
+- **Maintenance as Xcode, swift-build and the build server move.** Xcode updates or upstream changes can need updates to the fork or the setup. Mitigation: the people who use the setup do the updates, mostly with AI agents (the setup is small and has a README and tests). Xcode-only users and CI never depend on it.
 
 ### Risks
 
 - **Xcode updates can break the build server**, since it bundles its own swift-build. Mitigation: a pinned version and a check after each Xcode update. The worst case is that the setup stops working for the people who opted in; Xcode and CI aren't affected.
-- **Upstream doesn't accept the changes** or the project is abandoned. Mitigation: keep a fork under the DuckDuckGo organization (the changes are ~550 lines plus tests), or drop the setup.
+- **Malicious code in the build server or its dependencies** (supply chain). It runs on developer machines with access to the source code and the network. Mitigations:
+  - we build it from source at a pinned commit of our fork; nothing is downloaded prebuilt or updated automatically;
+  - its own code is small (~1,700 lines in 13 Swift files upstream, plus ~550 lines of our changes), so each upstream update can be reviewed as a diff before it goes into the fork;
+  - its dependencies come from Apple/swiftlang (swift-build, swift-tools-protocols, swift-argument-parser) and are pinned too.
+- **Upstream doesn't accept the changes** or the project is abandoned. Mitigation: the fork already carries our changes, so nothing breaks; we keep it, or drop the setup.
 - **Xcode and the editor share the index.** Both write to Xcode's index store; deleting the DerivedData folder resets it, as today.
 
 ## Testing
@@ -86,7 +92,7 @@ Add an opt-in VS Code setup to the repository: a workspace file and a few script
 
 ## Additional Considerations
 
-- **Privacy / Security:** No change to the apps. The install script builds the build server from its public repository at a pinned version, and everything runs locally.
+- **Privacy / Security:** No change to the apps and no user data involved; the setup only runs locally on developer machines. It does add third-party code to those machines, built from our fork at a pinned commit (see Risks). **Question for reviewers:** does a developer tool like this need a privacy/security triage? It's a small open-source package with Apple-only dependencies, so a light review of the fork may be enough.
 - **Site Breakage / Experimentation / Localization:** Not applicable.
 - **Operational:** No CI or release change.