Mirage VFS Adapter Authoring

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 and TypeScript; 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 and example.
• TypeScript guide and example.

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. 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 derives streaming from read and existence from stat, and defaults to a remote resource. A derived stream still fetches the entire file; it is not a memory-efficient stream.

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:

• read_stream / readStream, 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_scan / beforeFullScan 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. 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 function only your class declares is reachable through the dispatcher by name once it is marked @vfs_call(effect=Effect.READ) / @vfsCall({ effect: Effect.READ }); the effect tells a read-only mount and its policies what the call does. Use the installed version's signatures, including optional index parameters. Older versions assembled a VFSAdapter of callbacks instead of methods; follow the guide matching the installed package.

Give the VFS a unique name and a concise prompt describing the tree and rendering. Let Mirage derive commands, globbing, and dispatcher ops from the functions it defines. Add bespoke commands or overrides for behavior the generic operations cannot express.

Scope belongs in the resource operations too: a direct read, stream, range read, or ID-addressed command must not bypass filters enforced by listing. Prove parent membership or resolve through a scoped index. An incomplete listing cannot prove an unlisted resource absent. Use Mirage's existing hierarchy/index helpers when their documented contract fits; do not import private helpers merely to shorten the adapter.

Grep/rg optimizations must return the same matches as searching the rendered bytes. Fall back to scanning when equivalence is uncertain. Respect read budgets before eagerly materializing results, and report incomplete output.