Adding a New VFS

• Ship your own backend: a single TypeScript file in your own project or package, built on BaseVFS. No Mirage fork, no edits to Mirage source.
• Contribute a builtin: the four-layer layout inside the Mirage repo, mirrored in Python.

​

Ship Your Own Backend

import {
  Accessor,
  BaseVFS,
  FileStat,
  MountMode,
  type PathSpec,
  VFSAdapter,
  Workspace,
} from '@struktoai/mirage-node'
import { parseConfigWithSchema, secretStr, z } from '@struktoai/mirage-core/vfs/secrets'

const JiraConfigSchema = z.object({ site: z.string(), token: secretStr() })
type JiraConfig = z.infer<typeof JiraConfigSchema>

class JiraAccessor extends Accessor {
  constructor(readonly client: JiraClient) {
    super()
  }
}

declare function readdir(accessor: JiraAccessor, path: PathSpec): Promise<string[]>
declare function readBytes(accessor: JiraAccessor, path: PathSpec): Promise<Uint8Array>
declare function stat(accessor: JiraAccessor, path: PathSpec): Promise<FileStat>

class JiraVFS extends BaseVFS<JiraAccessor> {
  constructor(input: Record<string, unknown>) {
    const config = parseConfigWithSchema(JiraConfigSchema, input)
    super({
      name: 'jira',
      accessor: new JiraAccessor(makeClient(config)),
      io: new VFSAdapter({ read: { readdir, readBytes, stat } }),
      prompt: 'Issues rendered as .json files.',
    })
  }

  override async close(): Promise<void> {
    if (this.isClosed) return
    try {
      await this.accessor.client.close()
    } finally {
      await super.close()
    }
  }
}

const ws = new Workspace({ '/jira/': new JiraVFS(cfg) }, { mode: MountMode.READ })

​

Add capabilities as the resource grows

import {
  type NativeReadOps,
  type ReadOps,
  type WriteOps,
  VFSAdapter,
} from '@struktoai/mirage-node'

const read: ReadOps<JiraAccessor> = { readdir, readBytes, stat }
const native: NativeReadOps<JiraAccessor> = { readStream, readRange }
const writes: WriteOps<JiraAccessor> = { write, unlink }
const adapter = new VFSAdapter({ read, native, writes })

• overrides drops a generic command you replace, and commands supplies the replacement (or any bespoke verb) from command({...}).
• ops layers an irregular VFS/FUSE handler over the derived set; one carrying no filetype shadows the derived op of the same name. autoOps: false opts out of deriving any. A verb the op table does not carry is not served: the mount answers Operation not supported for it, so a backend can be partial.
• sizesAlwaysKnown declares that stat sizes every file without fetching it, which is also what makes the mount legal on FSKit. supportsSnapshot declares that stat fills FileStat.fingerprint; setting it without that is not drift detection.

​

How the driver connects to a workspace

​

Native search and backend-specific core functions

import { type SearchOps, type SearchQuery, type DuOps } from '@struktoai/mirage-node'

declare function search(
  accessor: JiraAccessor,
  path: PathSpec,
  query: SearchQuery,
): Promise<string[] | null>

const searchOps: SearchOps<JiraAccessor> = { search }
const adapter = new VFSAdapter({ read, search: searchOps })

// Native size queries require both total size and leaf enumeration.
const du: DuOps<JiraAccessor> = { size, entries }

import { registerVfsFactory } from '@struktoai/mirage-node'

registerVfsFactory('jira', (config) => Promise.resolve(new JiraVFS(config)))

mounts:
  /jira:
    vfs: ./jira.mjs:JiraVFS
  /wiki:
    vfs: my-backends:WikiVFS

​

Contribute a Builtin VFS

​

File Structure

typescript/packages/<core|node|browser>/src/
  accessor/<name>.ts           # the client handle: transport and config
  core/<name>/
    client.ts                  # API calls, through core/api
    scope.ts                   # the scope table and detectScope (hierarchy kit)
    pathing.ts                 # <label>__<id> names (sanitizeName, makeIdName)
    normalize.ts               # the JSON a file renders
    readdir.ts stat.ts read.ts
  ops/<name>/index.ts          # ops derived from the CommandIO table
  commands/builtin/<name>/
    io.ts                      # VFSAdapter compiled to the shared IO table
    index.ts                   # <NAME>_COMMANDS
    <bespoke commands>.ts      # push-downs and verbs
  vfs/<name>/
    config.ts prompt.ts <name>.ts

​

1. Config, Accessor, and Registry

​

2. Core VFS Operations

• readdir(accessor, path, index?) returning child paths.
• read(accessor, path, index?) returning bytes.
• stat(accessor, path, index?) returning a FileStat.

• A reader that reaches the API by the ids in the path slots passes stat so the kit proves the file’s parent through the listing first. Without it, a path outside the configured scope (Trello’s workspaceId and boardIds) reads while ls and stat say it does not exist.
• A listing that is a filtered or truncated view (one page of a bounded query, a time window, a glob-scoped span) returns { entries, seeds: {}, partial: true }. Cached as the whole directory, it would prove every entry it left out absent.
• entryStat('<idKey>', ...) names the id under the key its path slot declares.
• Id-addressed commands honor the same scope knobs the listing does (Trello’s commands/builtin/trello/_scope.ts).

​

3. Ops Layer

import { IO } from '../../commands/builtin/qdrant/io.ts'
import { VFSName } from '../../types.ts'
import { makeGenericOps } from '../generic/factory.ts'
import type { RegisteredOp } from '../registry.ts'

export const QDRANT_OPS: readonly RegisteredOp[] = makeGenericOps(VFSName.QDRANT, IO)

​

4. Commands

• Declare native text search in new VFSAdapter({ read, search }). Generic grep/rg builders consume it only when search.meta.grep opts in; semantic search does not opt in. The hierarchy kit supplies makeSearchOp for scope-based core functions; unsupported requests fall back to scanning. Existing wrappers may call runSearch(X_IO, name, ...) when preserving a custom registration.
• A verb (trello card create) declares its own new CommandSpec({...}) with every id as a flag, reads flags through new FlagView(opts.flags, SPEC) (never flags.get(...)), registers write: true for a mutation, and calls requireMountWritable(...) before the client. Specs declared inline are dumped to .cache/spec/typescript/<node|browser>/vfs_commands/ and compared with Python’s, and a prompt that teaches the verbs is pinned against their specs (vfs/trello/prompt.test.ts).
• A handler that reads its accessor directly is trusted host code. Admission judges the paths it is given, but no policy sees what it reads below them, so keep such a handler to its operands.

​

5. VFS Class

import { BaseVFS } from '../base.ts'

export class MyVFS extends BaseVFS {
  override readonly name: string = VFSName.MY_VFS
  override readonly cachesReads: boolean = true
  override readonly prompt: string = MY_PROMPT
  override readonly accessor: MyAccessor

  constructor(config: MyConfig) {
    super()
    this.config = resolveMyConfig(config)
    this.accessor = new MyAccessor(this.config)
  }

  override ops(): readonly RegisteredOp[] {
    return MY_VFS_OPS
  }

  override commands(): readonly RegisteredCommand[] {
    return MY_VFS_COMMANDS
  }
}

​

Point lookups under fresh

​

Listing versions

• ListingVersion.NONE (the default): no version; every command re-lists.
• ListingVersion.MOUNT: one version covers every listing of the mount (GitHub and the Hub use the head commit). A stat of the mount root through the gate’s empty check store (ListingCheckStore, cache/index/ram) asks the backend and returns it as fingerprint; through any other index it names none and reads neither the index nor the backend, since nothing reads a root fingerprint off a mount-view stat. The tree fill stores the same value with every listing it writes (seed(..., version) or setDir(..., { version })).
• ListingVersion.FOLDER: each listing carries its own folder’s version (disk). A stat of the folder returns it as the fingerprint, and readdir reads it before listing and passes it to setDir(path, entries, expiresAt, { version }), so a change during the scan leaves the stored version behind.

​

6. Snapshot Support

1. stat() returns a stable FileStat.fingerprint.
2. Every read record includes the fingerprint that produced those bytes.
3. If the backend supports immutable revisions, reads consult the resolved revision and record it.

​

7. Verification

• Tests for config parsing (an unknown key refused), path layout, every VFS op, command behavior, read-only enforcement, scope enforcement, state redaction, and cleanup.
• Rebuild the dists (core, then node, then browser), regenerate spec/ with typescript/scripts/gen-specs.ts and scripts/gen_specs.py, then run scripts/check_spec_parity.py, scripts/check_layout_parity.py --strict and pnpm typecheck.
• An integration target in integ/targets.json with cases under integ/vfs/<name>/, run by both hosts’ runners against the same goldens; a SaaS backend gets a fake under integ/server/. Any change in observable shell behavior adds a case.

​

Updating Existing Backends

​

From GenericVFS and the VFS interface

​

Check the adapter contract

import { checkReadContract, type ReadFixture } from '@struktoai/mirage-node'

const fixture: ReadFixture = {
  file: filePath,
  directory: parentPath,
  missing: missingPath,
  content: new TextEncoder().encode('known fixture bytes'),
}
await checkReadContract(adapter, accessor, fixture)

import { checkDriverContract, DriverOps } from '@struktoai/mirage-node'

await new DriverOps(vfs).write(filePath, new TextEncoder().encode('known fixture bytes'))
await checkDriverContract(vfs, fixture)

​

Batch resource search

​

Start from a packaged example