PR #9220 - ParadevAI/Paradev

Finding

From the biweekly fresh-Mac onboarding walkthrough (page). The run used desktop v2.0.2 on a clean macOS 26 VM with no Xcode Command Line Tools, no Homebrew and no gh.

Blocker. Without the Command Line Tools, /usr/bin/git is Apple's stub. It opens the "install command line developer tools" prompt and fails. Every way to add the first project runs git, and onboarding has no skip. The results:
- "Empty project" seemed to do nothing. Apple's prompt opened behind the window.
- "Open a folder" → "Initialize & import" went back to the picker with no message.
- "Clone a repo" showed the raw xcode-select error.
When Homebrew is missing, the "Install GitHub CLI" tile opens cli.github.com. That page leads with brew install gh.
"Empty project" puts new projects in ~/.superset/projects by default. That folder is hidden and uses the old brand name.

What changed

1. Missing git / Command Line Tools: fixed

New electronTrpc.system.detectGit, built the same way as detectGhCli/detectBrew (execWithShellEnv). On macOS, when the git on PATH is /usr/bin/git, it first checks that xcode-select -p succeeds and that <developer dir>/usr/bin/git exists. Only then does it run git --version. This means the 4 s poll never runs the stub, so it cannot open Apple's prompt again and again. A git found somewhere else on PATH is used directly. If the tools exist but git still refuses to run (for example, the Xcode license was never accepted), the first stderr line comes back in error. Linux and Windows only run git --version.
New electronTrpc.system.installCommandLineTools. It runs xcode-select --install and is macOS only.
Project step (onboarding/project/page.tsx): when git is missing, a quiet row appears above the tiles. It uses the tile background, so there is no new banner style. It says "Paradev needs Git to add a project." with one of these:
- macOS without the tools: "On a Mac, Git comes with Apple's Command Line Tools." and an Install Command Line Tools button. After a click: "Finish Apple's installer. This page updates when it's done."
- The tools are there but git fails: git's own reason.
- Other platforms: "Install Git, then come back." and a Get Git button (git-scm.com/downloads).
While git is missing, the four add-project tiles are disabled, so none of them can fail silently. The page polls every 4 s while git is missing and stops once it works. The row then disappears and the tiles turn on.
Detection can be wrong. If a stub error still gets through, clone, folder import and empty project now show the same plain message, not the raw output.
No skip added. A project here is a git repository: empty project runs git init, and clone, import and templates need git too. The main window cannot do anything useful without git. "Skip for now" was also removed on purpose in #5185. The way forward is the explanation plus the one-click install, and the page updates when the install finishes.

2. GitHub CLI install link: fixed

On macOS without Homebrew, the tile now opens https://github.com/cli/cli/releases/latest, which has the macOS .pkg. Homebrew users still get the in-app brew install dialog. Other platforms still go to cli.github.com.

3. Default project location: fixed (`~/Paradev`)

The default is a renderer-only value. It was written out four times (onboarding clone, EmptyProjectModal, NewProjectModal, TemplateGalleryModal). All four now use getDefaultProjectsDir(homeDir), which returns ~/Paradev. Why this does not affect existing users:

Projects store their absolute mainRepoPath, so existing projects and worktrees stay where they are. Worktrees live under ~/.superset/worktrees, which this does not touch.
The host-service only gets parentDir from the caller and creates it when it is missing (ensureParentDirectory). It has no default of its own. v1 createEmptyRepo runs mkdir -p, and v1 clone uses git clone, which creates parent folders.
~/.superset/projects/<repoPath>/config.json (per-machine setup overrides in host-service/runtime/setup/config.ts and desktop/.../setup.ts) is keyed by repo path, not by where projects live. It still works for projects in any location.
No migration reads this path.

Verification

bun test src/lib/trpc/routers/system src/renderer/routes/_authenticated/onboarding (apps/desktop): 13 pass, 0 fail. New tests: detect-git.test.ts (7) and isGitToolsMissingError.test.ts (3). To check that the tests can fail, I removed the macOS branch of detectGit. Two tests failed ("does not run the Apple stub…", "treats a developer directory without git as missing tools").
Real-machine check of detectGit with real execFile, PATH=/usr/bin:/bin (so which git = the Apple stub path), on a Mac with Xcode: { installed: true, version: "2.54.0", needsCommandLineTools: false }. With fileExists forced to false (developer dir has no git): { installed: false, needsCommandLineTools: true }, and the stub was not run.
bun run typecheck (apps/desktop): exit 0, no errors.
bun run lint:fix: "Checked 12177 files … No fixes applied."
bun run check:i18n: exit 0. Seven new strings, translated by hand in all 17 locales. "Paradev", "Git", "Apple" and "Command Line Tools" are kept as product names.
Full bun test in apps/desktop: 9030 pass, 36 fail. All 36 failures are in suites that start real git processes or shells (git.test.ts, shell-env.test.ts, worktree import, git-task-handlers, branch-detached-worktree), and the log shows posix_spawn failed: EAGAIN. Re-run on their own, those files pass (39/0 and 28/0). None of them touch the changed code.

UI not verified in the app. I did not run the dev desktop app or drive onboarding over CDP. The worktree had no .env to start the dev stack. This Mac also has Xcode installed, and the Command Line Tools cannot be uninstalled here, so the no-tools state could not be reproduced. There are no screenshots. Before merging, please check on the fresh-Mac VM rig: the project step shows the Install row and disabled tiles, the button opens Apple's installer, and the page updates once the install finishes.

Summary by cubic

Fixes onboarding on a fresh Mac without Apple's Command Line Tools, where /usr/bin/git is a stub that fails (and pops Apple's install prompt) so all four add-project options previously failed silently or showed raw xcode-select errors.

Git missing state

New system.detectGit checks xcode-select before running the stub on macOS so polling never opens Apple's prompt, and system.installCommandLineTools runs xcode-select --install and activates Apple's installer, which otherwise opens behind the Paradev window.
The project step explains why git is missing, offers Install Command Line Tools (or a Git download link outside macOS), disables the add-project tiles, and polls every 4 s until git works. The notice follows Apple's installer window and offers Try again or Show Apple's installer if it closes or never opens, and shows xcode-select's reason inline.
host-service turns stub refusals in clone, init, and folder import into a plain PRECONDITION_FAILED instead of raw output; Open a folder no longer offers git init on a real repo when git cannot run.

Other onboarding fixes

Without Homebrew, the GitHub CLI tile opens the gh release page (which ships the macOS .pkg) instead of cli.github.com, which leads with brew install.
New projects now default to ~/Paradev instead of the hidden ~/.superset/projects; existing projects keep their paths because they store absolute locations, so no migration is needed.

Summary by CodeRabbit

New Features
- The onboarding flow now checks whether Git is installed and provides platform-specific setup guidance, including an option to launch Apple’s Command Line Tools installer on macOS.
- Project creation and cloning now use a default Paradev folder in your home directory.
- GitHub CLI setup links now direct you to the appropriate download page for your platform.
Improvements
- Project creation options are unavailable while Git is missing, and Git-related errors include tailored guidance.
- Git setup messages are now available in supported languages.