Filesystem API & Bash

The Mesa SDK integrates with Vercel’s just-bash library to provide shell execution against Mesa repositories without needing a sandbox. This page covers the API surface exposed through @mesadev/sdk. For a higher-level overview, see the Mesa just-bash guide.

Imports

The SDK re-exports the core just-bash types alongside the Mesa filesystem:

import { Mesa, Bash, MesaFileSystem } from "@mesadev/sdk";
import type {
  BashOptions,
  ExecResult,
  BashLogger,
  CommandName,
  ChangeEditArgs,
  ChangeNewArgs,
  ChangeListArgs,
  ChangeResult,
  ChangeInfo,
  CustomCommand,
  BookmarkCreateArgs,
  BookmarkListArgs,
  NetworkConfig,
  JavaScriptConfig,
  SecureFetch,
} from "@mesadev/sdk";

Mounting a Filesystem

Use mesa.fs.mount() to mount a MesaFileSystem instance scoped to specific repositories:

const mesa = new Mesa({ apiKey: process.env.MESA_API_KEY });

const fs = await mesa.fs.mount({
  repos: [
    { name: "my-repo", bookmark: "main" },
    { name: "another-repo", bookmark: "feature-branch" },
  ],
  mode: "rw",
  cache: {
    diskCache: {
      path: "/tmp/mesa-cache",
      maxSizeBytes: 1024 * 1024 * 1024,
    },
  },
});

`MesaFileSystemConfig`

Field	Type	Description
`repos`	`RepoConfig[]`	Repositories to mount. Optionally specify `bookmark` or `changeId` to control the base revision.
`mode`	`"ro" \| "rw"`	Read-only or read-write access
`cache`	`object`	Optional caching configuration
`cache.diskCache.path`	`string`	Path for on-disk cache
`cache.diskCache.maxSizeBytes`	`number`	Maximum cache size in bytes

Getting a Bash Shell

Call .bash() on a MesaFileSystem to get a Bash instance:

const bash = fs.bash({
  env: { NODE_ENV: "production", CI: "true" },
  cwd: "/acme/my-repo",
});

`MesaBashOptions`

Option	Type	Description
`env`	`Record<string, string>`	Environment variables for the shell
`cwd`	`string`	Initial working directory
`executionLimits`	`object`	Resource limits (timeouts, memory)
`fetch`	`typeof fetch`	Custom fetch for network access
`network`	`NetworkConfig`	Network access configuration
`python`	`object`	Python runtime configuration
`javascript`	`JavaScriptConfig`	JavaScript runtime configuration
`commands`	`CommandName[]`	Built-in commands to enable
`customCommands`	`CustomCommand[]`	User-defined commands
`logger`	`BashLogger`	Logging interface

Executing Commands

`bash.exec(command)`

Runs a shell command and returns the result.

const result = await bash.exec("ls -la /acme/my-repo/src");

`ExecResult`

Field	Type	Description
`stdout`	`string`	Standard output
`stderr`	`string`	Standard error
`exitCode`	`number`	Exit code (`0` = success)

const result = await bash.exec("grep -r 'TODO' /acme/my-repo/src");

if (result.exitCode === 0) {
  console.log("Found TODOs:", result.stdout);
} else {
  console.log("No matches or error:", result.stderr);
}

IFileSystem Methods

The MesaFileSystem class implements the full IFileSystem interface from just-bash. All methods are async unless noted.

Reading

Method	Returns	Description
`readFile(path, options?)`	`string`	Read file with encoding
`readFileBuffer(path)`	`Buffer`	Read file as raw bytes
`readdir(path)`	`string[]`	List directory entry names
`readdirWithFileTypes(path)`	`DirEntry[]`	List directory with type info
`readlink(path)`	`string`	Read symlink target

Writing

Method	Returns	Description
`writeFile(path, content, options?)`	`void`	Write string or bytes
`appendFile(path, content, options?)`	`void`	Append to file
`mkdir(path, options?)`	`void`	Create directory

Querying

Method	Returns	Description
`exists(path)`	`boolean`	Check file existence
`stat(path)`	`Metadata`	File metadata (follows symlinks)
`lstat(path)`	`Metadata`	File metadata (no symlink follow)
`realpath(path)`	`string`	Resolve canonical path
`resolvePath(base, path)`	`string`	Pure path resolution (sync)

Modifying

Method	Returns	Description
`rm(path, options?)`	`void`	Remove file or directory
`cp(src, dest, options?)`	`void`	Copy file or directory
`mv(src, dest)`	`void`	Move or rename
`chmod(path, mode)`	`void`	Change permissions
`utimes(path, atime, mtime)`	`void`	Set timestamps
`symlink(target, linkPath)`	`void`	Create symbolic link
`link(existing, new)`	—	Always returns `ENOTSUP`

Change and Bookmark APIs

MesaFileSystem also exposes two namespace-style API groups:

fs.change for creating or switching changes
fs.bookmark for bookmark management

`fs.change.new(args)`

Create a new change and switch to it.

const result = await fs.change.new({
  repo: "my-repo",
  bookmark: "main",
});

console.log(result.changeOid);

Exactly one of bookmark or changeId must be set.

`fs.change.edit(args)`

Switch to an existing change. This does not create a new change.

await fs.change.edit({
  repo: "my-repo",
  bookmark: "feature-branch",
});

Or switch by change ID:

await fs.change.edit({
  repo: "my-repo",
  changeId: "abc123...",
});

`fs.change.list(args)`

List changes reachable from the current checkout’s commit.

const changes = await fs.change.list({
  repo: "my-repo",
  limit: 10,
});

for (const change of changes) {
  console.log(change.changeId, change.commitOid);
}

Returns an array of ChangeInfo objects, each with:

Field	Type	Description
`changeId`	`string`	Hex-encoded change ID
`commitOid`	`string`	Hex-encoded commit OID the change points to

The limit parameter defaults to 50. Pass 0 for no limit.

`fs.bookmark.create(args)`

Create a bookmark on the current commit without switching.

await fs.bookmark.create({
  repo: "my-repo",
  name: "feature-branch",
});

`fs.bookmark.move(args)`

Move an existing bookmark to point at the specified change. Useful after a first write through a mount forks a new change — move the bookmark to publish the forked change.

await fs.bookmark.move({
  repo: "my-repo",
  name: "feature-branch",
  changeId: "abc123...",
});

`fs.bookmark.list(args)`

List bookmark names for a repository.

const bookmarks = await fs.bookmark.list({ repo: "my-repo" });
// ["main", "feature-branch", ...]

Type Summary

API	Args type	Return type
`fs.change.new`	`ChangeNewArgs`	`Promise<ChangeResult>`
`fs.change.edit`	`ChangeEditArgs`	`Promise<ChangeResult>`
`fs.change.list`	`ChangeListArgs`	`Promise<ChangeInfo[]>`
`fs.bookmark.create`	`BookmarkCreateArgs`	`Promise<void>`
`fs.bookmark.move`	`BookmarkMoveArgs`	`Promise<void>`
`fs.bookmark.list`	`BookmarkListArgs`	`Promise<string[]>`

SDK

CLI

Git Server

REST API

Filesystem API & Bash

Imports

Mounting a Filesystem

`MesaFileSystemConfig`

Getting a Bash Shell

`MesaBashOptions`

Executing Commands

`bash.exec(command)`

`ExecResult`

IFileSystem Methods

Reading

Writing

Querying

Modifying

Change and Bookmark APIs

`fs.change.new(args)`

`fs.change.edit(args)`

`fs.change.list(args)`

`fs.bookmark.create(args)`

`fs.bookmark.move(args)`

`fs.bookmark.list(args)`

Type Summary

SDK

CLI

Git Server

REST API

Documentation Index

​Imports

​Mounting a Filesystem

​MesaFileSystemConfig

​Getting a Bash Shell

​MesaBashOptions

​Executing Commands

​bash.exec(command)

​ExecResult

​IFileSystem Methods

​Reading

​Writing

​Querying

​Modifying

​Change and Bookmark APIs

​fs.change.new(args)

​fs.change.edit(args)

​fs.change.list(args)

​fs.bookmark.create(args)

​fs.bookmark.move(args)

​fs.bookmark.list(args)

​Type Summary

Imports

Mounting a Filesystem

`MesaFileSystemConfig`

Getting a Bash Shell

`MesaBashOptions`

Executing Commands

`bash.exec(command)`

`ExecResult`

IFileSystem Methods

Reading

Writing

Querying

Modifying

Change and Bookmark APIs

`fs.change.new(args)`

`fs.change.edit(args)`

`fs.change.list(args)`

`fs.bookmark.create(args)`

`fs.bookmark.move(args)`

`fs.bookmark.list(args)`

Type Summary