/mirage-vfs-authoring

name: mirage-vfs-authoring
description: Build or extend a custom Mirage VFS adapter for a user's API, database, object store, or application data. Use when connecting a new resource to Mirage, implementing a backend, or packaging a reusable adapter. For reading or editing data in an existing mount, use the filesystem workflow instead.

Author a Mirage VFS

Deliver an adapter in the user's project, a working mount configuration, and tests of its filesystem behavior. Subclass `BaseVFS` and define the functions the resource supports. A normal custom backend needs no Mirage fork.

Start from the bundled adapter

For a new backend, run `python scripts/new_adapter.py --language python --output <project>/resource.py` from this skill directory, or select `typescript` and a `.ts` output. The script refuses to overwrite an existing file. The generated adapter uses only an in-memory fixture and includes a read-contract check plus a mounted shell smoke test. Run Python with the project's Mirage environment, or TypeScript with its `tsx` runner and `@struktoai/mirage-node` dependency.

Replace the fixture client with the resource API, then update the fixture paths and expected bytes. Keep credentials in the application's configuration. The self-contained templates are [Python](assets/adapter.py) and [TypeScript](assets/adapter.ts); no repository checkout is needed to scaffold.

Establish the resource contract

Inspect the project's Mirage version, language, runtime, and existing client. Use the installed API and matching source or documentation; the interface is still evolving. Ask only for missing decisions that affect the implementation: which resources are visible, the mount prefix, credentials, and required writes.

Reuse a builtin VFS when it already represents the resource. For a new adapter, define a small example tree and what each leaf renders before implementing it. Separate stored bytes from rendered records, and distinguish a complete directory from a paginated or time-windowed view. Use stable resource identities when display names can collide or change.

Consult the relevant language's guide and runnable example, using the revision matching the target Mirage package:

• [Python guide](https://github.com/strukto-ai/mirage/blob/main/docs/python/vfs/new.mdx)

and [example](https://github.com/strukto-ai/mirage/blob/main/examples/python/vfs/new/custom_vfs.py).

• [TypeScript guide](https://github.com/strukto-ai/mirage/blob/main/docs/typescript/vfs/new.mdx)

and [example](https://github.com/strukto-ai/mirage/blob/main/examples/typescript/vfs/new/custom_vfs.ts).

Implement the smallest VFS

Keep backend access async. An `Accessor` owns the client; implement its cleanup when the adapter owns connections. Reuse connections across calls. Python constructors and `build_vfs` are synchronous: perform network initialization lazily in async operations. TypeScript class references can use `static async create` when initialization requires I/O.

Subclass `BaseVFS` and define these functions over `PathSpec`:

• `readdir`: return immediate child virtual paths in the format the installed

example uses. Avoid fetching each child's contents just to list a directory.

• `read`: return the exact bytes represented by a leaf, or an async iterator

of them for a file too large to hold. It also receives an `offset` and `size`; leave `reads_ranges` / `readsRanges` false and Mirage cuts the window from the whole read.

• `stat`: classify the entry and return its rendered byte length, or

`None` / `null` when the length is unknown without reading it.

Those three are the whole minimal VFS. Mirage collects a streamed `read` for a caller that needs the whole file, derives existence from `stat`, and defaults to a remote resource.

Builtin backends define these same functions. Core functions need not inherit a class: call them from the methods and wrap client-specific arguments or return values at the VFS boundary. The shared types live in `vfs/types`.

Define more functions independently as the resource needs them. A function the VFS does not define answers `Operation not supported`:

• `exists`, `find`, and `du_size` with

`du_entries` / `duSize` with `duEntries` are native fast paths. They preserve the baseline read semantics. Set `reads_ranges` / `readsRanges` when `read` fetches only the asked window: `offset` plus `size` is an exclusive end, and an omitted size reads through EOF.

• `search` is optional resource search for the `search` command, over a

`PathSpec` and `SearchQuery` with `query` text and backend-defined JSON `options`. No regex support or grep compatibility is assumed. Return text records, an empty list for no matches, or `None` / `null` to decline. Validate resource-specific options and propagate failures. Define optional `search_many` / `searchMany` when ranking and limits must apply once across several scopes.

• `files_containing` / `filesContaining` and `lines_containing` /

`linesContaining` let grep and rg skip reads: the files under a directory, or the lines of one file, that may hold a plain text. Answer every match or return `None` / `null`; a missed hit is a wrong answer. `before_full_walk` / `beforeFullWalk` may raise to refuse a scan no search could narrow.

• `write`, `append`, `pwrite`, `create`, `mkdir`, `unlink`, `rmdir`, `rm_r` /

`rmR`, `rename`, `copy`, `truncate`, and `setattr` are individual mutations. `write` and `append` take bytes or an async iterator of them; `materialize` collects one for a store that takes a single body. Defining `write` does not imply deletion, rename, or directory support; `append` and `pwrite` are built from `read` and `write` when the VFS does not define them. Mount mode still enforces which supported writes may execute.

A service action that is not a file, such as a query language search or a comment on a record, belongs in a CLI registered next to the mount, not in a VFS function. Use the in