bun-fs-helpers

# Bun Filesystem Helpers

Pure Bun-native filesystem utilities from `@side-quest/core/fs` - zero node:fs dependencies, command-injection safe.

## When to Use

- **Writing new code** - Always prefer these over node:fs
- **Command injection concerns** - All shell commands use array args (safe)
- **Token efficiency** - Smaller imports, faster operations
- **Bun-first projects** - Leverages Bun's native APIs

## Available Functions

### File Existence

```typescript
import { pathExists, pathExistsSync } from "@side-quest/core/fs";

// Async
if (await pathExists("/path/to/file")) { }

// Sync
if (pathExistsSync("/path/to/file")) { }
```

**Implementation**: Uses `Bun.file().exists()` (async) or `test -e` command (sync)

### Reading Files

```typescript
import { readTextFile, readTextFileSync, readJsonFile, readJsonFileSync } from "@side-quest/core/fs";

// Async text
const content = await readTextFile("/path/to/file.txt");

// Sync text
const content = readTextFileSync("/path/to/file.txt");

// Async JSON
const data = await readJsonFile<MyType>("/path/to/data.json");

// Sync JSON
const data = readJsonFileSync<MyType>("/path/to/data.json");
```

**Implementation**: Uses `Bun.file().text()` (async) or `cat` command (sync)

### Writing Files

```typescript
import { writeTextFile, writeTextFileSync, writeJsonFile, writeJsonFileSync } from "@side-quest/core/fs";

// Async text
await writeTextFile("/path/to/file.txt", "content");

// Sync text
writeTextFileSync("/path/to/file.txt", "content");

// Async JSON
await writeJsonFile("/path/to/data.json", { foo: "bar" }, 2);

// Sync JSON
writeJsonFileSync("/path/to/data.json", { foo: "bar" }, 2);
```

**Implementation**: Uses `Bun.write()` (async) or `printf` via shell (sync)

### Directory Operations

```typescript
import { ensureDir, ensureDirSync, readDir, readDirAsync } from "@side-quest/core/fs";

// Create directory (recursive)
await ensureDir("/path/to/nested/dir");
ensureDirSync("/path/to/nested/dir");

// List directory