@nestos/vfsdriver-local

Local filesystem backend for @nestos/vfs-core. File content remains on disk; SQLite sidecars hold metadata, tags and SeqFile records. Includes atomic file replacement and recoverable namespace renames.

Runtime dependencies are @nestos/vfs-core and better-sqlite3. Project organization, synchronization policy and execution belong to the host.

Structured SeqFile controls use typed projection tables and compound indexes while preserving the authoritative entry string. Both better-sqlite3 and the host Node SQLite adapter share the SQL implementation. Schema installation, backfill, ordinary writes and receipts participate in the same transaction; SQLite triggers keep projections synchronized for legacy write paths. rowControl is optional on custom sidecars and unsupported implementations do not scan JSON as a fallback. Read queries project only requested columns and use keyset pages without an implicit count. Files declaring the same layout share a physical table; durable renames preserve it and deletion clears record data and unused layouts.

Development

git clone --recurse-submodules [email protected]:nest-agentos/vfsdriver-local.git
cd vfsdriver-local
pnpm install --frozen-lockfile
pnpm typecheck
pnpm test
pnpm build
pnpm pack

CI uses Node.js 22. better-sqlite3 is a native dependency; installation needs a matching prebuilt binary or a native build toolchain. Its build is explicitly allowed in pnpm-workspace.yaml.

vendor/vfs-core pins core for standalone development. Inside itookit, the outer workspace resolves its top-level core instead. Packed releases reference core as an npm dependency and exclude the development submodule.

Usage

import { createVFS } from '@nestos/vfs-core';
import { LocalFSBackend } from '@nestos/vfsdriver-local';

const backend = new LocalFSBackend({
  rootDir: '/path/to/project',
  sidecarDir: '/path/to/project/.nestos/vfs',
});
const { manager } = await createVFS({ rootBackend: backend });
const fs = await manager.openFileSystem('/');
await fs.driver.createFile({ parentPath: '/', name: 'hello.txt', content: 'Hello' });
await manager.dispose();

@nestos/vfsdriver-local/node exports NodeFsOps and BetterSqliteSidecarDb for Node hosts that inject these implementations. The root entry retains its browser-safe interface for desktop hosts with their own filesystem bridge.

See AGENTS.md for transactions, recovery and performance invariants. Driver tests are self-contained. Kernel IPC and CLI SQLite integration tests are maintained by itookit under apps/cli/tests.

itookit integration

git submodule update --init --recursive packages/vfs-core packages/vfsdriver-local