fix(server): surface readable Windows Explorer reveal errors

[floklein]

Windows Reveal in File Explorer returns success as soon as PowerShell starts, hiding later launch failures from the existing error toast. Capturing those failures also exposes PowerShell's raw CLIXML output. This change makes those errors detectable and readable: wait for the short-lived helper, check its exit status, reject missing targets, and return the exception message as plain text while preserving Explorer's selection quoting.

Fixes #11172, which tracks error reporting. The originally reported Explorer no-op was not reproduced, and this PR does not claim to diagnose or fix its unknown cause.

Validation:

• Focused Windows launcher suite: 12 passed, 13 platform-specific tests skipped. Regression tests failed before the fixes and cover failed helpers, missing targets, missing launchers, and readable stderr. Real PowerShell checks preserve selection quoting.
• Two source links with line numbers opened their expected Explorer folders through the context menu in an isolated web client running this PR. The real launcher also opened a valid filename containing spaces and an apostrophe, and returned readable Path does not exist: ... text for a missing file. Native Electron context-menu interaction was not independently verified.
• Targeted lint/format checks pass. Server/contracts typechecks passed for the initial implementation; the follow-up changes only the generated PowerShell string and assertions.

Implemented by GPT-6 using Codex.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: a1608be8-6b63-420b-82ee-f83d84439ede

📥 Commits

Reviewing files that changed from the base of the PR and between c52b8d9 and 16b691e.

📒 Files selected for processing (3)

• apps/server/src/process/externalLauncher.test.ts
• apps/server/src/process/externalLauncher.ts
• packages/contracts/src/editor.ts

Included review availability: Your plan provides up to 10 included reviews per hour; 8 remain after this review.

---

📝 Walkthrough

Walkthrough

The change makes Windows Explorer reveal launches wait for helper completion, capture stderr, validate target paths in PowerShell, and return detailed errors. Tests cover failed helpers, missing targets, missing launchers, and valid temporary files.

Changes

Explorer reveal error handling

Layer / File(s)	Summary
Reveal error contract packages/contracts/src/editor.ts	ExternalLauncherEditorSpawnError accepts optional detail text and includes it in the error message.
Synchronous reveal launch flow apps/server/src/process/externalLauncher.ts	Explorer reveals set waitForExit. The launcher captures stderr and exit status, applies a timeout, and reports failed helper processes. PowerShell validates the target before Start-Process.
Failure and platform coverage apps/server/src/process/externalLauncher.test.ts	Tests cover stderr propagation, missing targets, missing launchers, expected PowerShell source, and valid temporary targets.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~25 minutes

Severity of issue fixed: Medium

Sequence Diagram(s)

sequenceDiagram
  participant fileExplorerRevealLaunch
  participant launchEditorProcess
  participant PowerShell
  fileExplorerRevealLaunch->>launchEditorProcess: set waitForExit
  launchEditorProcess->>PowerShell: spawn reveal helper with piped stderr
  PowerShell->>PowerShell: validate target with Test-Path
  PowerShell-->>launchEditorProcess: return exit code and stderr
  launchEditorProcess-->>fileExplorerRevealLaunch: return success or ExternalLauncherEditorSpawnError

Loading

Suggested reviewers: juliusmarminge, t3dotgg

Merge Risk: ⚪ Minimal · up to 16b69

Windows reveal failures are handled with actionable errors and focused coverage.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 33.33% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 3 functions across 3 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The changes satisfy issue #11172 by waiting for the Windows reveal helper, capturing stderr and exit status, reporting actionable failures, rejecting missing targets, preserving quoting, and adding fo…
Out of Scope Changes check	✅ Passed	All modified files support Windows Explorer reveal failure handling, error reporting, and focused regression coverage. No unrelated code changes are evident.
Title check	✅ Passed	The title clearly and concisely describes the main change: surfacing readable Windows Explorer reveal errors.
Description check	✅ Passed	The description explains what changed, why it changed, validation performed, scope limits, and the linked issue. The UI Changes section is not needed because this is not a UI change. The template chec…

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands.}