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, 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 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.

Wire configuration and state

For an embedded application, mount the VFS instance directly. For YAML or a reusable package, use the supported class reference or registration path:

• Python: CONFIG_CLS with register_vfs, a mirage.vfs package entry point, or a ./backend.py:ResourceVFS reference.
• TypeScript: registerVfs or a Node-loadable ./backend.mjs:ResourceVFS reference. Do not assume a browser can load a local Node module.

Validate config at this boundary. Python models should explicitly forbid unknown keys; TypeScript needs runtime validation, not a type assertion. Use the host's credential mechanism and secret types; avoid serializing credentials into state or errors.

Keep the default needs_override state for a live external resource unless reconstruction is deliberately implemented. For Mirage-owned in-memory data, implement state save/load and test restoration. Enable snapshot fingerprints, read revalidation, and known-size claims only when the operations fulfill those contracts.

Verify and deliver

Exercise the adapter through Workspace, with a fake service or fixture:

• Listing, reading, stat, globbing, and a representative search agree.
• Nested mount prefixes resolve correctly; missing paths fail consistently.
• Direct reads of excluded resources fail even when their IDs are known.
• Pagination and read limits do not silently omit data or prove false absence.
• A read-only mount refuses supported writes before the mutation reaches the service; unsupported operations fail clearly.
• Config typos fail, owned clients close, and promised state restoration works.

Use the user's language for an external adapter. When contributing a Mirage builtin, follow the repository's mirrored Python/TypeScript layout and gates, and add shared integration cases for observable shell behavior.

Deliver the adapter, exact mount configuration, and verification results. State which operations and state behavior are supported, and identify any live-service checks that could not be run.

Reuse the conformance check

Run check_read_contract / checkReadContract with a ReadFixture describing a small known file, its parent, an absent sibling, and expected bytes. This checks listing, stat, byte reads, streams, native ranges, existence, and missing-path errors without mutating the resource. It takes the VFS itself, so the same probe works for builtins and external backends.

For a writable backend, run check_mutation_contract / checkMutationContract with a MutationFixture naming an empty, disposable scratch directory. It checks every write precondition the VFS declares in condition_support / conditionSupport, then rename and copy of one file, and unlinks the files it wrote, pass or fail. A fake that cannot enforce a declared condition names it in unenforced; the check skips it with a warning.

Each conditional op runs through run_with_versions / runWithVersions, which binds the write context a write: conditional mount would, holding the version a session read at each path (None / null for a path it found absent). Use it to test a backend's own conditional writes, copies and deletes the same way.

import { checkMutationContract, runWithVersions, type MutationFixture } from '@struktoai/mirage-core'

const scratch: MutationFixture = {
  directory: new PathSpec({ virtual: '/resource/scratch', directory: '/resource', vfsPath: 'scratch' }),
}
await checkMutationContract(vfs, scratch)
await runWithVersions(vfs, [[file, null]], () => vfs.write(file, bytes))

Add backend-specific tests for pagination, authorization errors, and query options. Use disposable fixtures for mutation tests. Verify a read-only mount refuses writes and preserves the fixture. Do not run write probes against production data.