fs.mount() - Mesa Docs

mesa.fs.mount(...) returns a MesaFileSystem backed by Mesa’s native filesystem implementation. It mounts repositories at their canonical /<org>/<repo> paths. To mount them at paths you choose, call mesa.fs({ layout }) and mount the definition it returns.

import { Buffer } from 'node:buffer';
import { Mesa } from '@mesadev/sdk';

const mesa = new Mesa({ privateKey: process.env.MESA_PRIVATE_KEY });
const fs = await mesa.fs.mount({
  repos: [{ name: 'app' }],
  authors: [{ name: 'Mesa Bot', email: 'mesa-bot@example.com' }],
});

const data = await fs.readFileBuffer('/acme/app/README.md');
console.log(Buffer.from(data).toString('utf8'));

repos.list() results can be passed directly into mount() when you want to mount a filtered set of live repositories. Omit changeId to mount the default live state instead of pinning each repo to the response’s head_change_id.

const { repos } = await mesa.repos.list({
  tags: {
    $and: [{ environment: 'prod' }, { workload: { $in: ['sync', 'index'] } }],
  },
});

const fs = await mesa.fs.mount({
  repos,
  authors: [{ name: 'Mesa Bot', email: 'mesa-bot@example.com' }],
});

Private-key clients sign a short-lived, repo-scoped token locally, while a client built from an access token forwards that token unchanged. Either way the mount keeps the token it started with for its whole lifetime; nothing refreshes it in the background.

Options

RepoConfig[]

required

Repositories to mount. The array must be non-empty.

[{ name: string; email?: string }, ...]

Commit authors, in order, with at least one entry. Private-key mounts require this; access-token mounts reject it.

number | undefined

Lifetime of the mount, in seconds. Private-key mounts default to 900 and allow up to 14400. A client built from an access token cannot set ttl.

{ path: string; maxSizeBytes?: number } | undefined

Optional on-disk cache. When omitted, the mount uses in-memory caching only.

'error' | 'warn' | 'info' | 'debug' | undefined

Minimum native log level. Defaults to warn.

(record: LogRecord) => void | undefined

Per-instance structured log callback from the native filesystem.

RepoConfig

Open an existing revision, or fork a new named revision at mount time.

const fs = await mesa.fs.mount({
  repos: [
    {
      name: 'app',
      mode: 'rw',
      branchedFrom: {
        bookmark: 'main',
        as: { bookmark: 'run-27', describe: 'initiate plan...' },
      },
    },
    {
      name: 'docs',
      mode: 'ro',
      at: { bookmark: 'main' },
    },
  ],
  authors: [{ name: 'Mesa Bot' }],
});

string

required

Repository name.

'rw' | 'ro' | undefined

'rw' (default) or 'ro'. Read-only mounts cannot use branchedFrom.

RevisionIdentifier | undefined

Existing revision to open: { bookmark } or { changeId }. Mutually exclusive with branchedFrom. When omitted, the repo default bookmark is used.

BranchedRevision | undefined

Fork a new empty descendant from a parent tip and check it out. Optionally create as.bookmark and/or set as.describe. Omit as (or as.bookmark) for an anonymous tip. Requires writable mode. Parent bookmark is not moved.

Disk cache

const fs = await mesa.fs.mount({
  repos: [{ name: 'app' }],
  authors: [{ name: 'Mesa Bot' }],
  cache: { diskCache: { path: '/tmp/mesa-cache', maxSizeBytes: 500_000_000 } },
});

string

required

Directory for the on-disk cache.

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

Layout definitions

Calling mesa.fs({ layout, ttl }) builds an FsLayoutDefinition: the prepared layout bundled with everything you can do with it. The call is synchronous, so the one-shot mount chains with a single await. A layout replaces the canonical browse tree entirely — the mount contains exactly the paths the layout declares. See Layouts for the layout format and its structural rules.

import { Mesa, repo } from '@mesadev/sdk';

const mesa = new Mesa({ privateKey: process.env.MESA_PRIVATE_KEY });

const fs = await mesa.fs({
  layout: { '/workspace': repo('app', { mode: 'rw', bookmark: 'main' }) },
  authors: [{ name: 'Mesa Bot', email: 'mesa-bot@example.com' }],
}).mount();

await fs.readdir('/'); // ['workspace']

LayoutSpec

required

Map of absolute mount path to one repo(...) declaration or an array of them. Built eagerly, so an invalid map throws InvalidOptionsError at the mesa.fs(...) call.

number | undefined

Lifetime, in seconds, of every token the definition mints — through token() and under the hood in mount(). Same defaults and limits as fs.mount(...). Not accepted by access-token clients, whose token lifetime is already fixed.

TokensCreateAuthor[] | undefined

Required for private-key clients, rejected for every other credential. Ordered commit attribution carried by the minted token.

Definition members

Layout

The prepared layout. layout().toString() produces the JSON document mesa mount --layout reads.

Promise<MesaFileSystem>

Mount the layout as the complete namespace. Accepts the non-token mount options (cache, telemetry); the mount’s token lifetime is the definition’s ttl.

Promise<TokensCreateResponse>

Mint the layout-scoped, least-privilege access token: repositories collected from every declaration and scoped by name, ['read'] when every mode is 'ro' and ['read', 'write'] otherwise. Not available on access-token clients, which already hold a token.

token() validates the layout structurally before minting, so an invalid layout fails there with the same error the mount would report. Repository names resolve only at mount time — a layout naming a nonexistent repository still mints a token and fails when the mount resolves it.

const definition = mesa.fs({
  layout: { '/workspace': repo('app', { mode: 'rw' }) },
  authors: [{ name: 'Mesa Bot', email: 'mesa-bot@example.com' }],
  ttl: 3600,
});

sandbox.writeFile('layout.json', definition.layout().toString());
const { token } = await definition.token();

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

Promise<string>

Read a file as text using a Node-compatible encoding. The binary encoding follows the just-bash latin1 byte-string convention.

Promise<Uint8Array>

Read raw file bytes.

Promise<void>

Replace file contents, creating the file if missing. Parent directories must already exist.

Promise<void>

Append text or bytes to a file, creating it if missing.

Promise<boolean>

Return whether a path exists. Follows symlinks.

Metadata and traversal

Promise<FsStat>

Return metadata for a path, following symlinks. mtime is a JavaScript Date.

Promise<FsStat>

Return metadata for a path without following symlinks. mtime is a JavaScript Date.

Promise<string[]>

Return entry names in a directory. Sort client-side if you need deterministic ordering.

Promise<Array<{ name: string; isFile: boolean; isDirectory: boolean; isSymbolicLink: boolean }>>

Return entry names with file type flags.

Promise<string>

Resolve symlinks and .. segments to a canonical path.

Promise<string>

Return the target of a symlink.

string

Join and normalize a path against a base path without touching the filesystem.

string[]

Return a synchronous snapshot of paths known to the filesystem.

Mutations

Promise<void>

Create a directory. With { recursive: true }, create missing parents and do nothing when the path already exists as a directory.

Promise<void>

Remove a file or directory. Use { recursive: true } for non-empty directories and { force: true } to ignore missing paths.

Promise<void>

Copy a file or directory. Use { recursive: true } for directories.

Promise<void>

Move or rename a file or directory.

Promise<void>

Set permission bits, such as 0o755.

Promise<void>

Create a symlink. Relative targets are stored verbatim and resolve against the parent of linkPath at read time.

Promise<void>

Set access and modification times with JavaScript Date values.

Promise<void>

Create a hard link if supported by the native filesystem implementation.

Subscriptions

MesaFS reads and writes are realtime by default. Use subscriptions only when your process needs an event stream that identifies which paths changed, such as to refetch data and rerender a frontend.

Subscribe to filesystem invalidation events. The handler is called after the changed state is visible through this filesystem instance.

const subscription = fs.subscribe(async (event) => {
  if (!event.recursive) {
    const content = await fs.readFile(event.path, 'utf8');
    console.log(event.path, content);
  }
});

subscription.unsubscribe();

(event: WatchEvent) => void | Promise<void>

Callback invoked for each filesystem invalidation.

string

Absolute MesaFS path that changed, such as /acme/app/src/index.ts.

boolean

Whether descendants of path may have changed. Refresh any cached directory or subtree state below path when this is true.

void

Stop receiving events and close the underlying watcher.

FsStat

stat(...) and lstat(...) return FsStat.

boolean

Whether the path is a regular file.

boolean

Whether the path is a directory.

boolean

Whether the path is a symlink. This is false from stat(...) when the target exists because stat follows symlinks.

number

POSIX mode bits.

number

Size in bytes.

Date

Modification time.

Method namespace	Reference
`fs.bash(...)`	fs.bash()
`fs.change`	fs.change
`fs.bookmark`	fs.bookmark
`fs.subscribe(...)`	Advanced Realtime

Errors

Throws InvalidOptionsError for an empty repo list, a private-key ttl outside 1..14400, missing or rejected authors, or a layout that breaks the structural rules. A layout fails at the mesa.fs(...) call rather than at mount. Token signing or VCS connection failures can throw API errors or connection errors.

​Options

​RepoConfig

​Disk cache

​Paths

​Layout definitions

​Definition members

​Response

​MesaFileSystem

​Byte and text I/O

​Metadata and traversal

​Mutations

​Subscriptions

​FsStat

​Related filesystem methods

​Errors

Options

RepoConfig

Disk cache

Paths

Layout definitions

Definition members

Response

MesaFileSystem

Byte and text I/O

Metadata and traversal

Mutations

Subscriptions

FsStat

Related filesystem methods

Errors