## Fix TypeScript union type resolution for Commands.run() method
### What's Changed
Improved TypeScript type safety for the `Commands.run()` method by
adding proper function overloads to handle the union case when the
`background` parameter type is not known at compile time.
### Key Improvements
**Better Type Safety**
- Added a third function overload to correctly handle the `background?:
boolean` union case
- TypeScript now correctly infers return types:
- `background: true` → returns `CommandHandle`
- `background: false | undefined` → returns `CommandResult`
- `background: boolean` (unknown at compile time) → returns
`CommandHandle | CommandResult`
**Enhanced Developer Experience**
- Added comprehensive JSDoc overloads that clearly document each usage
pattern
- IntelliSense now provides accurate type hints and autocompletion
- Eliminates ambiguous union types when the `background` value is known
at compile time
**Prevents Runtime Errors**
- When `background` is a literal value, developers get precise types and
can't accidentally call wrong methods
- When `background` is a runtime boolean, TypeScript correctly shows the
union type requiring proper type narrowing
### Why This Matters for SDK Users
Before this change, developers had to ignore ts warning & manually cast
union types when using `commands.run()`:
```typescript
// Before: typescript was complaining, because it expected `true` or `false` as literals.
// Required manual casting:
// @ts-ignore
const result = await sbx.commands.run('ls', { background: isBackground }) as CommandHandle | CommandResult
```
After this change, TypeScript automatically infers the correct type:
```typescript
// After: TypeScript knows this is CommandHandle
const handle = await sbx.commands.run('ls', { background: true })
await handle.wait() // ✅ TypeScript knows .wait() is available
// TypeScript knows this is CommandResult
const result = await sbx.commands.run('ls')
console.log(result.stdout) // ✅ TypeScript knows .stdout is available
// When background value is unknown at compile time, returns union type
const isBackground: boolean = Math.random() > 0.5
const result = await commands.run('ls', { background: isBackground })
// result is CommandHandle | CommandResult - requires type narrowing or casting
```
Ben Fornefeld
8c43806f81