Filesystem Overview

Overview

This page describes filesystem-related globals available in bunmagic scripts, compatibility globals, and SAF deprecation status.

For the files.* API reference, see Files API.

Global Usage

In bunmagic scripts, filesystem helpers are global.

await files.ensureDir('./output')
await files.outputFile('./output/state.json', JSON.stringify({ ok: true }, null, 2))

if (await files.pathExists('./output/state.json')) {
  const state = JSON.parse(await files.readFile('./output/state.json')) as { ok?: boolean }
  console.log(state.ok)
}

For imported modules:

import * as files from 'bunmagic/files'
import { outputFile, pathExists } from 'bunmagic/files'

Primary API (Recommended)

Use files.* for new code.

Path/checks: resolve, stem, pathExists, isFile, isDir
Directory: ensureDir, ensureFile, emptyDir
Read/write: readFile, readBytes, writeFile, outputFile, editFile
Movement: copy, move, remove, glob
Collision-safe: ensureUniquePath, writeFileSafe, copySafe, moveSafe

Detailed reference: Files API

Compatibility Globals

These exist in 1.4.x for compatibility:

isDirectory() -> forwards to files.isDir()
ensureDirectory() -> calls files.ensureDir() and returns true
glob()
resolveTilde()

Prefer files.* in new examples.

Path Helpers

`$HOME`

User home directory path.

Type: string

`resolveTilde()`

Usage: resolveTilde(input: string): string

Expands leading ~ in paths.

Parameters:

input - Path string

Returns:

Path with a leading ~ expanded to $HOME

Examples:

const p = resolveTilde("~/Projects")
console.log(p)

`cd()`

Usage: cd(path: string | SAF): void

Changes the current working directory.

When path is a string, the value is passed through resolveTilde(...). When path is a legacy SAF instance, bunmagic uses path.path.

Parameters:

path - Target directory path (string) or legacy SAF instance

Examples:

cd("~")
cd("~/Projects/bunmagic")

`cwd()`

Usage: cwd(): Promise<string>

Returns the current working directory path.

Returns:

Promise resolving to the current working directory path

JSON Pattern (Current API)

files.* does not include dedicated JSON helpers. Use explicit parse/stringify.

const p = './tmp/data.json'
const state = await files.pathExists(p)
  ? (JSON.parse(await files.readFile(p)) as Record<string, unknown>)
  : {}

state.updatedAt = new Date().toISOString()
await files.outputFile(p, `${JSON.stringify(state, null, 2)}\n`)

Editor Integration

`openEditor(path)`

Opens a file or directory in the configured editor.

await openEditor('~/Projects/my-script.ts')

SAF (Legacy, Deprecated)

Migration guide: /migrations/saf-to-files/

SAF remains available in 1.4.x for compatibility and emits a one-time deprecation warning unless silenced with BUNMAGIC_SILENCE_DEPRECATIONS=1.