dwmkerr / dwmkerr/shellwright

feat: improve error diagnostics for native module failures

Open
#30 0 comments 0 reactions 0 assignees View on GitHub
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.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.