Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.mesa.dev/llms.txt

Use this file to discover all available pages before exploring further.

mesa.fs.mount(...) returns a MesaFileSystem backed by Mesa’s native filesystem implementation. 
import { Buffer } from 'node:buffer';
import { Mesa } from '@mesadev/sdk';

const mesa = new Mesa({ org: 'acme' });
const fs = await mesa.fs.mount({ repos: [{ name: 'app' }] });

const data = await fs.readFileBuffer('/acme/app/README.md');
console.log(Buffer.from(data).toString('utf8'));
Under the hood, mount() resolves repository IDs, mints a scoped API key for the mounted repos, and connects to the VCS backend. The SDK attempts to revoke mounted keys on process shutdown and garbage collection.

​
Options

​
repos
RepoConfig[]
required
Repositories to mount. The array must be non-empty.
​
mode
'ro' | 'rw' | undefined
Access mode. Defaults to rw. Read-only mounts mint a read scoped key and reject write operations with read-only filesystem behavior.
​
cache.diskCache
{ path: string; maxSizeBytes?: number } | undefined
Optional on-disk cache. When omitted, the mount uses in-memory caching only.
​
telemetry.logLevel
'error' | 'warn' | 'info' | 'debug' | undefined
Minimum native log level. Defaults to warn.
​
telemetry.onLog
(record: LogRecord) => void | undefined
Per-instance structured log callback from the native filesystem.

​
RepoConfig

Pin a repository to a bookmark or change at mount time. 
const fs = await mesa.fs.mount({
  repos: [
    { name: 'app', bookmark: 'main' },
    { name: 'docs', changeId: 'zyxwvutsrqponmlkzyxwvutsrqponmlk' },
  ],
});
​
RepoConfig.name
string
required
Repository name.
​
RepoConfig.bookmark
string | undefined
Bookmark to check out. Mutually exclusive with changeId.
​
RepoConfig.changeId
string | undefined
Change ID to check out. Mutually exclusive with bookmark.

​
Disk cache

const fs = await mesa.fs.mount({
  repos: [{ name: 'app' }],
  cache: { diskCache: { path: '/tmp/mesa-cache', maxSizeBytes: 500_000_000 } },
});
​
cache.diskCache.path
string
required
Directory for the on-disk cache.
​
cache.diskCache.maxSizeBytes
number | undefined
Optional cache size cap. When omitted, the native extension auto-sizes the budget against system resources.

​
Paths

Mounted filesystem paths include the organization and repository name: 
/<org>/<repo>/README.md
/acme/app/src/main.ts

​
Response

Returns a Promise<MesaFileSystem>.

​
MesaFileSystem

The returned fs object implements the just-bash filesystem interface and exposes async file I/O, metadata, traversal, mutation, Bash, and mounted-repo version-control helpers. 
await fs.mkdir('/acme/app/src', { recursive: true });
await fs.writeFile('/acme/app/src/main.ts', 'console.log("hello")\n');
const data = await fs.readFile('/acme/app/src/main.ts', 'utf8');

​
Byte and text I/O

​
readFile(path, options?)
Promise<string>
Read a file as text using a Node-compatible encoding. The binary encoding follows the just-bash latin1 byte-string convention.
​
readFileBuffer(path)
Promise<Uint8Array>
Read raw file bytes.
​
writeFile(path, content, options?)
Promise<void>
Replace file contents, creating the file if missing. Parent directories must already exist.
​
appendFile(path, content, options?)
Promise<void>
Append text or bytes to a file, creating it if missing.
​
exists(path)
Promise<boolean>
Return whether a path exists. Follows symlinks.

​
Metadata and traversal

​
stat(path)
Promise<FsStat>
Return metadata for a path, following symlinks. mtime is a JavaScript Date.
​
lstat(path)
Promise<FsStat>
Return metadata for a path without following symlinks. mtime is a JavaScript Date.
​
readdir(path)
Promise<string[]>
Return entry names in a directory. Sort client-side if you need deterministic ordering.
​
readdirWithFileTypes(path)
Promise<Array<{ name: string; isFile: boolean; isDirectory: boolean; isSymbolicLink: boolean }>>
Return entry names with file type flags.
​
realpath(path)
Promise<string>
Resolve symlinks and .. segments to a canonical path.
​
readlink(path)
Promise<string>
Return the target of a symlink.
​
resolvePath(base, path)
string
Join and normalize a path against a base path without touching the filesystem.
​
getAllPaths()
string[]
Return a synchronous snapshot of paths known to the filesystem.

​
Mutations

​
mkdir(path, options?)
Promise<void>
Create a directory. With { recursive: true }, create missing parents and do nothing when the path already exists as a directory.
​
rm(path, options?)
Promise<void>
Remove a file or directory. Use { recursive: true } for non-empty directories and { force: true } to ignore missing paths.
​
cp(src, dest, options?)
Promise<void>
Copy a file or directory. Use { recursive: true } for directories.
​
mv(src, dest)
Promise<void>
Move or rename a file or directory.
​
chmod(path, mode)
Promise<void>
Set permission bits, such as 0o755.
​
symlink(target, linkPath)
Promise<void>
Create a symlink. Relative targets are stored verbatim and resolve against the parent of linkPath at read time.
​
utimes(path, atime, mtime)
Promise<void>
Set access and modification times with JavaScript Date values.
​
link(existingPath, newPath)
Promise<void>
Create a hard link if supported by the native filesystem implementation.

​
FsStat

stat(...) and lstat(...) return FsStat.
​
isFile
boolean
Whether the path is a regular file.
​
isDirectory
boolean
Whether the path is a directory.
​
isSymbolicLink
boolean
Whether the path is a symlink. This is false from stat(...) when the target exists because stat follows symlinks.
​
mode
number
POSIX mode bits.
​
size
number
Size in bytes.
​
mtime
Date
Modification time.
Method namespaceReference
fs.bash(...)fs.bash()
fs.changefs.change
fs.bookmarkfs.bookmark

​
Errors

Throws InvalidOptionsError for an empty repo list. API key minting, repo lookup, or VCS connection failures can throw API errors or connection errors.