feat: improve error diagnostics for native module failures
- Dominant language
- TypeScript
- Stars
- 37
- Forks
- 5
- Avg merge
- 3d 23h
- Merged PRs (30d)
- 1
Description
## Problem
When `node-pty` fails to load (e.g., missing prebuilt binaries), users see a cryptic error:
```
Error: posix_spawnp failed.
```
No context on what went wrong or how to fix it.
## Proposed Solutions
### 1. Startup diagnostics
Wrap node-pty import with helpful error handling:
```typescript
let pty;
try {
pty = await import('node-pty');
} catch (err) {
console.error(`[shellwright] Failed to load node-pty native module.`);
console.error(`[shellwright] This usually means compilation failed during install.`);
console.error(`[shellwright] Try: npm install -g @dwmkerr/shellwright`);
console.error(`[shellwright] Or install build tools: xcode-select --install (macOS)`);
console.error(`[shellwright] Original error:`, err.message);
process.exit(1);
}
```
### 2. Add `--verbose` flag
```bash
shellwright --verbose
```
Outputs:
- Node version
- Platform/arch
- node-pty binding path
- Any load errors
### 3. Document npx debugging
Add to README troubleshooting:
```bash
# See npx installation logs
npm_config_loglevel=verbose npx -y @dwmkerr/shellwright
# Or check npm cache
ls ~/.npm/_npx/*/node_modules/node-pty/build/
```
### 4. Health check endpoint (HTTP mode)
```
GET /health → { "status": "ok", "node_pty": "loaded", "version": "0.1.4" }
```
## Acceptance Criteria
- [ ] Startup catches node-pty load failures with actionable message
- [ ] `--verbose` flag shows diagnostic info
- [ ] README documents how to debug installation issues
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.